Revisar o histórico de lançamentos do ERP
Quando um fluxo de trabalho lança em um ERP — por meio da etapa Lançar documentos (consulte Lançar documentos em sistemas ERP) ou da etapa de lançamento própria de um sistema, como um lançamento contábil ou um cheque manual do Sage 100, um lançamento contábil do Sage Intacct ou do NetSuite, um documento do Acumatica, do Business Central ou do Xero, um lançamento contábil do Dynamics 365 Finance & Operations, do Oracle Fusion, do Workday Financials ou do SAP S/4HANA Cloud, ou um documento do SAP —, o PlaidCloud registra cada tentativa de lançamento em um livro de controle durável, por tenant, para que o mesmo documento nunca seja lançado duas vezes. O Histórico de lançamentos do ERP é a visão somente leitura desse livro: cada tentativa e seu estado atual, com o número de documento e os carimbos de data e hora do próprio ERP, filtrável por projeto.
Ele é complementar à tabela de resultado por execução que uma etapa de lançamento grava: a tabela de resultado reúne os resultados de uma execução, enquanto o Histórico de lançamentos é o registro permanente de todas as execuções e fluxos de trabalho, e acompanha cada lançamento por todo o seu ciclo de vida, em vez de congelá-lo no momento em que a execução terminou.
O que cada lançamento mostra
Seção intitulada “O que cada lançamento mostra”Cada linha é um documento lançado (ou com tentativa de lançamento) em um ambiente de ERP em uma conexão:
| Campo | Significado |
|---|---|
ledger_id |
O id da linha no livro de controle. |
project_id |
O projeto a partir do qual o lançamento foi feito. |
connection_id |
A conexão de ERP usada. |
environment_id |
O ambiente da conexão no qual se lançou (por exemplo, uma sandbox versus produção). |
natural_key |
A chave de negócio do documento, conforme derivada pela etapa de lançamento. |
mode |
live para um lançamento real, simulate para o que uma execução simulada teria lançado. |
state |
O estado atual do ciclo de vida do lançamento (veja abaixo). |
confirmation_id |
O número de documento do próprio ERP, quando o ERP atribui um. Nunca definido em um lançamento simulado. |
run_id |
A execução do fluxo de trabalho que fez o lançamento. |
submitted_at, created_at, updated_at |
Quando o lançamento foi enviado, registrado pela primeira vez e alterado pela última vez. |
Um lançamento feito no modo de simulação tem mode simulate, distinguindo-o de um lançamento real à primeira vista — consulte Lançamentos simulados abaixo.
Os estados do ciclo de vida
Seção intitulada “Os estados do ciclo de vida”Um lançamento passa por estes estados conforme o ERP o processa:
| Estado | Significado |
|---|---|
preflighted |
Validado e reservado, ainda não enviado ao ERP. |
submitted |
Enviado ao ERP; o resultado ainda não é conhecido. |
pending |
Aceito para processamento assíncrono; aguardando um resultado final. |
posted |
Lançamento confirmado; confirmation_id contém o número do documento do ERP. |
rejected |
O ERP recusou o lançamento. |
in_doubt |
Não foi possível confirmar o resultado — é preciso que uma pessoa verifique diretamente no ERP antes de qualquer nova tentativa. |
reversed |
Um documento lançado anteriormente foi estornado. |
O Registro de lançamentos mostra os mesmos lançamentos em um conjunto próprio e mais simples de estados.
Lançamentos simulados
Seção intitulada “Lançamentos simulados”Uma execução iniciada no modo de simulação valida o que uma etapa de lançamento enviaria, mas nunca contata o ERP. O que uma etapa de lançamento teria lançado é registrado aqui, com mode simulate, para que você o revise da mesma forma que revisa um lançamento real — incluindo seu natural_key — sem um confirmation_id, já que nenhum ERP chegou a vê-lo.
Os documentos simulados de uma etapa Lançar documentos também são registrados aqui, com mode simulate, exceto os de um sistema lançado por meio do agente do PlaidCloud (como SAP on-premise e Sage 100), que aparecem apenas no Registro de lançamentos como Seria lançado.
Uma entrada simulada nunca ocupa nem bloqueia o espaço que protege a gravação idempotente de um lançamento real. Se você executar o mesmo documento ao vivo depois, o lançamento real prossegue e substitui o registro simulado. Um espaço de trabalho sem livro de lançamentos configurado ainda valida normalmente uma execução simulada — apenas não registra nada aqui.
Limpe as entradas simuladas de um projeto independentemente das reais com DELETE /rest/v1/analyze/erp/write/history/simulated?project_id=<project> (opcionalmente restringido com connection_id), ou com a ferramenta MCP erp_clear_simulated_postings com os mesmos argumentos. De qualquer forma, somente as linhas simuladas são removidas — um lançamento real nunca é tocado. A mesma limpeza também remove os documentos das execuções de Lançar documentos do projeto que foram executadas em Simular e as cópias de lançamentos simulados do próprio Registro de lançamentos. A resposta informa cleared (linhas de histórico e documentos de execuções em Simular) e sims_cleared (as cópias do Registro).
Ler o histórico
Seção intitulada “Ler o histórico”Restrinja toda leitura a um projeto ao qual você tenha acesso. Você precisa de acesso de leitura a esse projeto — o mesmo acesso que o restante do seu trabalho no projeto exige.
Via REST
Seção intitulada “Via REST”GET /rest/v1/analyze/erp/write/history?project_id=<project>Parâmetros de consulta opcionais restringem o resultado:
| Parâmetro | Efeito |
|---|---|
connection_id |
Somente lançamentos feitos nesta conexão. |
state |
Somente lançamentos neste estado (por exemplo, state=in_doubt). |
mode |
live ou simulate. Sem ele, lançamentos reais e simulados aparecem juntos. |
limit |
Tamanho da página (padrão 100). |
cursor |
O next_cursor da página anterior. |
Os resultados vêm do mais recente para o mais antigo. Quando uma página atinge limit, a resposta traz um next_cursor; passe-o de volta como cursor para ler a próxima página e pare quando next_cursor for nulo.
Via MCP
Seção intitulada “Via MCP”Chame a ferramenta erp_post_history com os mesmos argumentos — project_id (obrigatório) e, opcionalmente, connection_id, state, mode, limit e cursor. Ela retorna as mesmas linhas, paginadas da mesma forma.
Revisões comuns
Seção intitulada “Revisões comuns”- Tudo o que ainda está em dúvida em um projeto:
state=in_doubt— os lançamentos a confirmar manualmente no ERP. - O que uma execução específica lançou: leia o histórico do projeto e filtre por
run_id. - Se um documento foi realmente lançado: encontre a linha dele e leia
stateeconfirmation_id.