Platform API: Traces, Warnings, and Transaction Detail

The Platform API has been significantly expanded, with a warning channel for problems that did not stop delivery and new endpoints for a single transaction, a whole trace and a trace’s logs, along with several changes to existing fields.

New endpoints:

• GET /platform/whoami returns the organization, key scope, key label and
  whether the key’s creator has accepted the service terms. It does not read your data, and it works with sandbox keys. The rest of the new endpoints require a standard API key.
• GET /platform/edi_transactions/:id returns one transaction with its status,
  its warnings, the flow that processed it, its own results, the 997 that
  acknowledged it (acknowledgedBy) or the document a 997 acknowledged
  (acknowledges), and its artifacts by role: input, output, errored and
  acknowledged.
• GET /platform/traces/:traceGuid returns the full processing run in one
  response: its transactions, results, feed entries, logs, and each artifact
  with the step that produced it. The processing flag turns false when
  the run has finished, so a poll after a submission knows when to stop.
• GET /platform/logs?trace=... returns a run’s log entries oldest first. The
  optional level filter takes info, warn or error.

Warnings are a new channel for problems that did not stop delivery. A warning
never changes a transaction’s status. Results carry them as
detail.warnings, the transaction list counts them as warningCount, and the
transaction detail lists them as warnings:

{
  "code": "mapping_failed",
  "message": "Mapping validation failed; the mapped document was delivered as produced. ...",
  "detail": {
    "kind": "validation",
    "errors": ["/heading must have required property fob_related_instructions_FOB"]
  },
  "resultId": "2b7d0c4e-aaaa-bbbb-cccc-ddddeeeeffff"
}

You can branch on code. The codes today:

• mapping_failed: an inbound mapping failed and the document was delivered
  anyway, so its output is not guaranteed to be your canonical shape. (Inbound transactions are always delivered even when they fail mapping validation; the same is not true for outbound transactions).
• sender_mismatch: the ISA sender is not the interchange id on the partner’s
  external envelope. The document was still processed under that partner.
• structural_error: the envelope arithmetic is wrong, such as an SE segment
  count that does not match or ST and SE control numbers that differ. The
  document was still delivered.
• invalid_date: a date element inside the transaction set could not be read
  as a date. The element was left out of the translation.

Additions to existing endpoints:

• The transaction list accepts direction (inbound or outbound),
  partner, status, warnings (true or false), since (inclusive) and
  until (exclusive). incoming still works, and sending it with a direction
  that disagrees returns 400. A row commits a moment after its createdAt, so
  end an until window a few seconds before now.
• Transactions carry direction, partnerKey, status and warningCount.
  incoming is still returned. duplicateOf names an earlier inbound
  transaction with the same sender and interchange control number. The repeat
  is still processed and gets its own 997.
• Results carry status (success or error) and nodeId. The results list
  accepts a status filter, and its node filter now accepts a node name as
  well as an id.
• When a mapping fails to run, its entry in detail.errors leads with the line
  and column in the mapping, for example
  line 12, column 5: Expected ")" before end of expression.
• A webhook delivery result carries detail.webhook with the url and the
  endpoint’s statusCode, and on a failure the response’s contentType,
  attempts and willRetry. The response body is not returned.
• detail.partner is now on every result a partner’s flow writes, failed steps
  included, however the document arrived.
• POST /platform/partners/:key/ts/:code now returns ediTransactionId, so you
  can fetch the transaction without searching by trace.
• A resend’s response now includes traceGuid. The resend lands on the original
  trace, its results carry detail.resend: true, and it adds its own feed entry
  marked the same way. If you count one delivery per document, deduplicate
  success entries on traceGuid rather than skipping resends, since the resend
  may be the only success.
• Resend has a new refusal, 422 document_not_generated, for a transaction that
  failed before a document was produced.
• The error reference now
  lists content_too_large (413, over the 1 MB processing limit), invalid_edi
  (422) and invalid_parameter (400), which some endpoints already returned.

Questions? Email info@tediware.com

This update was written with AI assistance. It has been reviewed and edited by a human.