Podrška

DTO Flow centar za pomoć

Praktične upute za pokretanje partnerskih razmjena, uspješan rad partnera, povezivanje sustava i dobivanje podrške kada je trebate.

Integracija

Webhookovi

Koristite webhookove kada drugi sustav treba reagirati nakon što DTO Flow primi, validira, prihvati ili propusti redovitu partnersku datoteku.

Istražite webhook isporuku za događaje partnerskih datoteka Pogledajte kako webhook aktivnosti ostaju sljedive

Postavljanje

Pretplate

Webhook pretplata povezuje niz DTO Flow događaja s jednom krajnjom točkom primatelja. Izradite zasebne pretplate za različita odredišta, okruženja ili odgovorne timove kako biste svaku integraciju mogli neovisno testirati, pauzirati, mijenjati joj tajnu i pregledavati njezinu povijest.

U produkciji koristite stabilnu HTTPS krajnju točku, primjerice https://example.com/webhooks/dtoflow.
Odaberite primjenjuje li se pretplata na sve feedove ili samo na odabrane feedove.
Pretplatite se samo na događaje koje primatelj treba, zatim suzite događaje dovršenih predaja po statusu kada primatelja zanimaju samo prihvaćene, odbijene ili neuspjele predaje.
Odmah pohranite tajnu za potpisivanje; DTO Flow prikazuje izvornu tajnu kada se izradi ili rotira.
Pošaljite testnu isporuku prije omogućavanja uvoza u odredišni sustav ili procesa upozoravanja.
Pregledajte povijest isporuke kada krajnja točka vrati pogrešku, ne odgovori na vrijeme ili je pretplata pauzirana.

Webhook pretplatama upravljajte nakon prijave u DTO Flow. Privatni pristupni tokeni namijenjeni su automatizaciji datoteka, a ne upravljanju webhookovima.

Isporuka

Ponašanje isporuke

DTO Flow šalje svaku isporuku kao HTTP POST s JSON sadržajem. Provjerite potpis nad izvornim tijelom zahtjeva, trajno zabilježite događaj ili stavite daljnju obradu u red te vratite 2xx odgovor bez odgode, a dulje radnje nastavite nakon potvrde primitka.

Isporuke uključuju Content-Type: application/json i User-Agent: DTO Flow Webhooks/1.0.
Svaki 2xx odgovor označava uspješnu isporuku. Odgovori izvan raspona 2xx, istek vremena i pogreške prijenosa bilježe se u povijesti isporuke.
DTO Flow za privremene neuspjehe izvodi najviše šest pokušaja isporuke. Odgode prije drugog do šestog pokušaja iznose 5 minuta, 10 minuta, 30 minuta, 1 sat i 2 sata.
Testne isporuke šalju se jednom kako ne bi nastavile s ponovnim pokušajima dok otklanjate pogreške.
Koristite DTOFlow-Event-Id i DTOFlow-Delivery-Id za idempotentnost i praćenje isporuke.
Ne oslanjajte se na redoslijed isporuke kada je aktivno više predaja, feedova ili ponovnih pokušaja.

Događaji

Sadržaji događaja

Sadržaji događaja namjerno su kompaktni. Uključuju stabilne ID-jeve, kontekst feeda i partnera, datume razdoblja, status predaje, status validacije, sažetke predanih datoteka i detalje roka kada se događaj odnosi na propušteno razdoblje.

feed.submission.available: Šalje se kada je predaja trenutačno prihvaćena za svoj feed, partnera i razdoblje. Koristite ovaj događaj za pokretanje uvoza ili dohvat prihvaćene predane datoteke ovlaštenim putem.
feed.submission.completed: Šalje se kada predaja dosegne završni status kao što je Validated, ValidationFailed, Delivered, DeliveryFailed, Rejected, ili Archived. Statusnim filtrima odredite koje dovršene predaje šalju obavijest krajnjoj točki.
feed.period.deadline_elapsed: Šalje se kada provjera roka zaključi da je očekivano razdoblje prošlo bez dovršene predaje.
webhook.test: Šalje se ručnom testnom isporukom kako biste mogli provjeriti usmjeravanje, provjere potpisa, zapise i postupanje s upozorenjima prije omogućavanja stvarnih događaja datoteka.

Zaglavlja potpisa su DTOFlow-Timestamp i DTOFlow-Signature-256. Primjeri provjeravaju HMAC potpis nad timestamp.rawBody i odbijaju vremenske oznake izvan zadanog petominutnog prozora zaštite od ponavljanja.

{
  "schemaVersion": 1,
  "eventId": "75c789c2-e5bb-4a7e-95cc-6ee78481ec8b",
  "eventType": "feed.submission.available",
  "occurredAt": "2026-06-01T12:04:31Z",
  "tenantId": "f6398077-653b-42fa-99af-2de4aca395c2",
  "tenantName": "Contoso Retail",
  "fileFeedId": "5306fb96-fb40-41d1-baa3-5d27922c5ea1",
  "fileFeedName": "Supplier Prices",
  "partnerId": "088cb758-a819-4116-9c91-d4f8bd59eb36",
  "partnerName": "Northwind Foods",
  "submissionId": "5dfc82ed-4d7d-42e2-9d90-580d0b36f0ee",
  "periodKey": "2026-06",
  "periodStart": "2026-06-01T00:00:00Z",
  "periodEnd": "2026-06-30T23:59:59Z",
  "dueAt": "2026-06-01T12:00:00Z",
  "overallStatus": "Validated",
  "overallValidationStatus": "Passed",
  "isCurrentAcceptedSubmission": true,
  "files": [
    {
      "fileId": "6022d3fd-c236-4672-ad9b-eb16f29eeff8",
      "feedFileId": "c067c23a-8a34-4131-bb3d-e77bd65d034a",
      "feedFileName": "Prices",
      "originalFileName": "prices.csv",
      "status": "Validated",
      "validationStatus": "Passed",
      "errorCount": 0,
      "warningCount": 2,
      "infoCount": 4,
      "sizeBytes": 18422,
      "contentType": "text/csv",
      "contentHash": "sha256:9d3f..."
    }
  ],
  "deadline": null
}

Primjeri

Primjeri primatelja

Počnite jednom rutom primatelja koja provjerava potpis, čita događaj, sigurno zanemaruje nepoznate vrste događaja i sporije radnje stavlja u red izvan ciklusa zahtjeva.

Obavijestite vanjski sustav kada partnerska datoteka postane trenutačna prihvaćena predaja.
Pokrenite interni uvoz nakon uspješne validacije.
Otvorite operativni zadatak kada dovršena predaja nije prošla validaciju ili obradu.
Zabilježite upozorenje za propušteno razdoblje kada dovršena datoteka nije stigla prije roka.

.NET referenca: .NET kartica predstavlja DtoFlow.Integration tipove. Prikazane klase, uključujući DtoFlowWebhookVerifier, DtoFlowWebhookHeaders, i DtoFlowWebhookEventCodes, prikazuju oblik klijenta. Trenutačne integracije izradite prema primjeru s izravnim HTTP pozivima i objavljenom OpenAPI ugovoru.

using DtoFlow.Integration;
using DtoFlow.Integration.Models;

var builder = WebApplication.CreateBuilder(args);
var signingSecret = builder.Configuration["DTOFLOW_WEBHOOK_SECRET"]
    ?? throw new InvalidOperationException("Set DTOFLOW_WEBHOOK_SECRET.");

var app = builder.Build();

app.MapPost("/webhooks/dtoflow", async (HttpRequest request) =>
{
    request.EnableBuffering();

    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var rawBody = buffer.ToArray();
    request.Body.Position = 0;

    var headers = DtoFlowWebhookHeaders.FromHeaderLookup(
        name => request.Headers[name].ToString());
    var verification = DtoFlowWebhookVerifier.Verify(rawBody, headers, signingSecret);

    if (!verification.IsValid)
    {
        app.Logger.LogWarning(
            "Rejected DTO Flow webhook delivery {DeliveryId}: {ErrorCode}.",
            headers.DeliveryId,
            verification.ErrorCode);

        return Results.Unauthorized();
    }

    if (!DtoFlowWebhookVerifier.TryDeserializePayload(rawBody, out var payload) ||
        payload is null)
    {
        return Results.BadRequest();
    }

    var eventCode = DtoFlowWebhookEventCodes.Parse(payload.EventType);
    switch (eventCode)
    {
        case DtoFlowWebhookEventCode.FeedSubmissionAvailable:
            QueueImport(payload);
            break;

        case DtoFlowWebhookEventCode.FeedPeriodDeadlineElapsed:
            AlertOperations(payload);
            break;

        case DtoFlowWebhookEventCode.Unknown:
            app.Logger.LogInformation("Ignored unknown DTO Flow event {EventType}.", payload.EventType);
            break;
    }

    return Results.Ok();
});

app.Run();

static void QueueImport(DtoFlowWebhookPayload payload)
{
    if (payload.SubmissionId is null || payload.IsCurrentAcceptedSubmission != true)
    {
        return;
    }

    Console.WriteLine($"Queue import for submission {payload.SubmissionId}.");
}

static void AlertOperations(DtoFlowWebhookPayload payload)
{
    Console.WriteLine($"Deadline elapsed for {payload.FileFeedName}: {payload.PeriodKey}.");
}

Referenca

Referenca za webhook primatelja

Kodu primatelja trebaju provjera potpisa, sigurno čitanje sadržaja i obrada kodova događaja. .NET kartica prikazuje referentni oblik istog ponašanja.

DtoFlowWebhookVerifier.Verify(...): Provjerava DTOFlow-Timestamp i DTOFlow-Signature-256 nad izvornim tijelom i tajnom za potpisivanje.
DtoFlowWebhookVerifier.TryDeserializePayload(...): Sigurno parsira JSON sadržaj u DtoFlowWebhookPayload bez bacanja iznimke za neispravan JSON.
DtoFlowWebhookEventCodes.Parse(...): Povezuje nazive događaja poput feed.submission.completed u stabilne vrijednosti kako bi kod primatelja mogao koristiti preglednu switch naredbu.
DtoFlowSubmissionStatusCodes.Parse(...): Parsira vrijednosti statusa predaje kao što su Validated, ValidationFailed, i DeliveryFailed.

using DtoFlow.Integration;
using DtoFlow.Integration.Models;

static void HandleDtoFlowEvent(DtoFlowWebhookPayload payload)
{
    var eventCode = DtoFlowWebhookEventCodes.Parse(payload.EventType);
    var submissionStatus = DtoFlowSubmissionStatusCodes.Parse(payload.OverallStatus);
    var validationStatus = DtoFlowValidationStatusCodes.Parse(payload.OverallValidationStatus);

    switch (eventCode)
    {
        case DtoFlowWebhookEventCode.FeedSubmissionCompleted:
            if (submissionStatus == DtoFlowSubmissionStatusCode.ValidationFailed)
            {
                Console.WriteLine($"Submission {payload.SubmissionId} failed validation.");
            }

            if (validationStatus == DtoFlowValidationStatusCode.Passed)
            {
                Console.WriteLine($"Submission {payload.SubmissionId} passed validation.");
            }
            break;

        case DtoFlowWebhookEventCode.FeedSubmissionAvailable:
            foreach (var file in payload.Files)
            {
                var fileStatus = DtoFlowSubmittedFileStatusCodes.Parse(file.Status);
                Console.WriteLine($"{file.OriginalFileName}: {fileStatus}, errors={file.ErrorCount}");
            }
            break;

        case DtoFlowWebhookEventCode.FeedPeriodDeadlineElapsed:
            var outcome = DtoFlowDeadlineOutcomeCodes.Parse(payload.Deadline?.Outcome);
            Console.WriteLine($"Deadline event {outcome} for period {payload.PeriodKey}.");
            break;
    }
}