DocTransform

Execuções

Como uma execução é criada, como você sabe que terminou e como tentá-la de novo sem cobrar duas vezes.

Resposta imediata ou 202

POST /templates/{id}/runs espera até 30 segundos para a execução terminar. Se terminar, você recebe 201 com a execução concluída e a saída pronta para baixar. Passados os 30 segundos, você recebe 202, um cabeçalho Location que aponta para a execução e um cabeçalho Retry-After que diz quanto esperar antes de consultar.

Um envio de CSV pode enviar delimiter e header_row junto com file, substituindo os valores detectados só para aquela execução:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -F "file=@/path/to/your/file.csv" \
  -F "delimiter=;" \
  -F "header_row=0"

Se uma coluna foi renomeada, a execução responde TEMPLATE_COLUMNS_MISSING com missing_columns: cada coluna que o modelo lê, com as colunas do arquivo para escolher. Nada é cobrado. Tente de novo com column_mapping, um objeto JSON {"coluna do arquivo": "coluna do modelo"}, só para essa execução; nunca é salvo. Uma coluna que só difere em maiúsculas, espaços ou sublinhados é associada sozinha e informada como aviso COLUMN_MATCHED.

Consultar o status

GET /runs/{id} responde a execução com o status: running, succeeded ou failed. Consulte-a, esperando o que Retry-After indicar, até ela se definir. Cada campo está na Referência da API. Em vez de consultar, adicione um webhook e o DocTransform avisa quando uma execução termina.

curl "https://doctransform.xyz/api/v1/runs/run_abc" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Baixar o resultado

GET /runs/{id}/output baixa o arquivo. A saída de uma execução concluída fica disponível por 30 minutos, ou por 3 dias quando um webhook recebe a execução; depois disso, ou para um id desconhecido, responde RUN_NOT_FOUND.

curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -o result.csv

Quando um arquivo não pode ser executado

Uma execução não tem nenhum conjunto de dados em andamento: cada arquivo de que ela precisa chega na requisição. Uma requisição que não pode ser executada é recusada de saída, nunca uma execução falha para consultar.

Um modelo que nomeia o sistema para o qual envia acrescenta à execução bem-sucedida um destination_check: passed, rows_checked, rows_failing e uma entrada de reasons para cada regra que falha, com seu rule_id, o cabeçalho field, outcome, count e uma message fixa. Traz apenas contagens, nunca um valor do seu arquivo. Uma verificação que falha não faz a execução falhar: status, código de status e cobrança são os de qualquer execução bem-sucedida, então um script pode decidir por passed antes de enviar. É null quando o modelo não nomeia nenhum sistema e até a execução ser bem-sucedida.

Uma execução bem-sucedida também devolve, ao lado da saída, um arquivo ou o ZIP das partes, um change_report: lines em inglês com as linhas alteradas por coluna e as contagens em steps. Só contagens e cabeçalhos, nunca um valor do seu arquivo. null até a execução ser bem-sucedida.

Cada execução bem-sucedida guarda as suas contagens no modelo. Na seguinte, cada passo do change_report traz as contagens anteriores em previous, emparelhadas por step_key; um passo novo ou editado tem new_or_changed. Uma contagem de pelo menos o dobro ou no máximo a metade da anterior, com 10 linhas ou mais de diferença, aparece em swings e acrescenta um aviso CHANGE_COUNT_SWING a warnings. Nunca faz a execução falhar. Uma execução para Excel ganha uma aba Changes final; para CSV, JSON ou XML, o arquivo vem como está, sem o .zip do app.

Uma execução de um modelo com divisão em arquivos que escreve duas ou mais partes devolve um application/zip chamado <nome>.zip, um arquivo por parte; com uma só, devolve esse arquivo. output.split_parts conta os arquivos, null sem divisão. Uma divisão em mais de 100 partes faz a execução falhar com FILE_SPLIT_TOO_MANY_PARTSe não escreve nenhum arquivo.

Um modelo com passos de data não precisa de nenhum parâmetro extra. Num passo Tempo entre datas, um início ou um fim vazio é lido como a data UTC em que a execução foi criada, então repetir o mesmo pedido conta até o mesmo dia. Num passo Parte da data, os nomes de mês e de dia da semana saem no name_language próprio do passo.

Enviar um arquivo de união

Um modelo com uma etapa de união sobre um arquivo enviado a cada execução precisa desse arquivo na requisição. Envie-o como mais uma parte file: não há nome de campo a escolher nem ordem a manter. A execução associa cada parte ao arquivo principal ou a um arquivo de união pelo ajuste do seu cabeçalho, então as partes podem vir em qualquer ordem:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -F "file=@/path/to/orders.csv" \
  -F "file=@/path/to/catalog.csv"

Uma execução que dá certo pode levar avisos de união em warnings: JOIN_UNMATCHED_ROWS quando linhas não acharam correspondência, JOIN_REPEATED_KEYS quando a tabela repete uma chave e usa-se a primeira linha, JOIN_CLOSE_MATCHES quando linhas foram casadas com uma grafia parecida e JOIN_CLOSE_MATCH_LIMIT quando a busca de grafias parecidas parou no limite. Cada um leva contagens. Os poucos valores de exemplo vêm só na resposta 201 que iniciou a execução: GET /runs/{id} e uma repetição com a mesma Idempotency-Key respondem "sample": null só com as contagens.

A execução também lista reference_tables: id, nome, última alteração e número de linhas de cada tabela lida, como estavam ao começar. Uma tabela substituída enquanto a execução anda não a altera.

Tentar de novo com Idempotency-Key

Envie um cabeçalho Idempotency-Key com a requisição de criação. Uma nova tentativa de rede da mesma requisição devolve a execução já iniciada para aquela chave, em vez de iniciar, e cobrar, uma segunda:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -H "Idempotency-Key: 3f2b9c1e-7a54-4d0e-9b61-0c8d5e2a41f7" \
  -F "file=@/path/to/your/file.csv"

Reutilizar uma chave com uma requisição diferente responde IDEMPOTENCY_KEY_REUSED. Uma execução que termina como RUN_INTERRUPTED ou RUN_TIMEOUT, ou cujo id responde RUN_NOT_FOUND, pode ser reenviada com a mesma chave.