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.csvQuando 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 arquivo sem uma coluna de que o modelo precisa: TEMPLATE_COLUMNS_MISSING.
- Várias partes
filepara um modelo sem passo Append: TEMPLATE_TAKES_ONE_FILE. Mais partes do que seu plano permite: FILE_COUNT_LIMIT_EXCEEDED. - Um arquivo que é a própria saída deste modelo: TEMPLATE_OUTPUT_AS_SOURCE. Nada é cobrado.
- Uma execução bem-sucedida ainda pode trazer uma lista
warnings, com uma entrada APPEND_LOCALE_DISAGREEMENT para cada parte cujos números são lidos de modo diferente com seus próprios separadores. Nada é convertido. - Um modelo com planilha Summary adiciona um aviso quando a planilha não pode ser escrita porque o modelo não é Excel: SUMMARY_SHEET_NOT_WRITTEN. Adiciona outro quando a planilha tem quase tantas linhas quanto os dados: SUMMARY_SHEET_ONE_GROUP_PER_ROW. Uma planilha Summary que não pode ser construída faz a execução falhar com SUMMARY_SHEET_BROKEN. Essa execução com falha não é cobrada.
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"- Um arquivo de união que não foi enviado: JOIN_FILE_MISSING. Uma parte sem colunas de que a etapa precisa, inclusive um arquivo principal enviado onde vai um arquivo de união: JOIN_FILE_COLUMNS_MISSING.
- Duas partes que se encaixam igualmente bem no mesmo arquivo e não podem ser distinguidas: RUN_FILES_AMBIGUOUS.
- Um modelo que une uma tabela de referência salva que não existe mais, inclusive uma excluída: REFERENCE_TABLE_NOT_FOUND, com o nome da tabela na mensagem. Uma coluna que a etapa lê e que a tabela não tem mais: REFERENCE_TABLE_COLUMN_MISSING.
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.