Não existe listagem simples de cards de um flow. Uma chamada direta a GET /v1/flows/{id}/cards retorna erro 404 (rota inexistente). Para obter todos os cards de um flow, é necessário percorrer as fases do flow e agregar os resultados chamando a listagem por fase uma vez para cada uma, ou usar o endpoint de busca quando há um termo específico.
A atualização de propriedades do card rejeita phaseId. Movimentar um card sempre deve ser feito pelo endpoint de movimentação — ele valida se os campos obrigatórios da fase atual foram preenchidos antes de permitir a saída dela; a tentativa de mover um card via atualização genérica retorna erro 400.
A movimentação de fase valida um conjunto restrito de fases de destino permitidas a partir da fase atual — esse conjunto é mais restrito do que o total de fases teoricamente alcançáveis exibido na interface do flow. Mover para uma fase fora desse conjunto, ou para a fase em que o card já está, retorna erro 422.
A atualização de campos de fase substitui todo o conjunto de campos da fase atual, não é incremental: enviar apenas alguns campos apaga os demais que não foram incluídos na chamada. Campos do formulário de entrada incluídos no mesmo envio são ignorados silenciosamente.
O endpoint de atualização de campos via link público não deve ser usado em um card já existente e em andamento — pode apagar (zerar) os campos da fase atual sem atualizar os campos de formulário de entrada pretendidos, e sem retornar nenhum erro HTTP. Seu uso correto é exclusivamente o fluxo de submissão pública inicial.
Campos nativos preenchidos automaticamente a partir do formulário de entrada (por exemplo, nome, documento e valor solicitado do cliente) tornam-se imutáveis após a criação do card — tentativas de alterá-los retornam um no-op silencioso ou erro 500, dependendo do endpoint usado. A única forma de corrigi-los é recriar o card.
A atualização do responsável pelo card exige um objeto completo com identificador, nome e e-mail do usuário — não apenas um identificador solto. O nome é gravado como um retrato congelado no card e não é resolvido novamente a partir do cadastro do usuário em leituras futuras.
Etiquetas não têm endpoint de escrita direta. A única rota relacionada é a de leitura; etiquetas são aplicadas exclusivamente por automações configuradas no flow. Etiquetas aplicadas na criação do card podem levar um curto intervalo até aparecerem em uma leitura imediatamente subsequente.
O indicador de card finalizado não deve ser tratado como uma função determinística apenas da fase atual logo após uma movimentação: fases de encerramento negativo tendem a refletir o novo estado de forma síncrona, enquanto fases de encerramento positivo podem levar um curto intervalo. Recomendamos basear integrações no identificador da fase atual combinado com a configuração da própria fase.
O registro de anexos armazena apenas metadados (uma referência/caminho do arquivo) — o upload do conteúdo binário é feito por um mecanismo separado, não coberto pelos endpoints deste domínio.
Remoção de cards em lote e remoção de membros de grupo são operações destrutivas e irreversíveis — não há confirmação adicional nem possibilidade de restauração.
Ao executar o motor de crédito sobre um card (documentado no domínio de motores), o identificador de policy usado no caminho da chamada não é o identificador da policy configurada no motor, mas sim o identificador retornado pela listagem de policies do motor de crédito do flow — os dois identificadores são diferentes e não são intercambiáveis.
