# Połącz aplikację z automatyzacją

Wyślij zdarzenie z aplikacji, gdy w Twoim systemie coś się wydarzy, na przykład zostanie utworzone zamówienie lub wpłynie płatność. Zdarzenie może uruchomić przebieg, kontynuować przebieg oczekujący na to zdarzenie lub anulować przebieg z pasującą regułą anulowania. Każda automatyzacja ma jeden URL zdarzeń do wszystkich trzech zastosowań.

> Automations is in Early access. Your workspace permissions determine which actions you can perform.

Jeśli nie możesz otworzyć Automations ani utworzyć wersji roboczej, zobacz [dostęp do obszaru roboczego i kontrola edycji](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard).

## Skonfiguruj zdarzenie uruchamiające przebieg

1. Utwórz automatyzację z wyzwalaczem **Event from your application**.
2. Ustaw **Event name**, na przykład `order.created`. Nazwy rozróżniają wielkość liter i mogą zawierać litery, cyfry, kropki, podkreślenia oraz myślniki.
3. Zdefiniuj **Event fields** dla danych wysyłanych przez aplikację. Dla zamówienia dodaj pole tekstowe o nazwie `order_id`. Późniejsze kroki mogą korzystać z tych pól.
4. Opublikuj automatyzację. Ekran potwierdzenia wyświetla sekcję **How to start a run** z adresem URL zdarzenia i przykładowym żądaniem.

Aby ponownie znaleźć szczegóły połączenia, zaznacz wyzwalacz i kliknij **How to connect your application** w szybkiej edycji. Rozwinięty edytor pokazuje kontrolki połączenia.

## Symuluj wersję roboczą lub wykonaj opublikowaną wersję

Użyj **Preview workflow** z przykładowymi danymi, aby zasymulować wersję roboczą bez wysyłania wiadomości i zmieniania danych. Uruchomienie polecenia cURL, kliknięcie **Send event…** lub użycie **Start run** wykonuje opublikowaną automatyzację i może realizować rzeczywiste akcje. Zapisane i niezapisane zmiany wersji roboczej nie mają wpływu na te przebiegi.

Opublikuj automatyzację przed wysłaniem zdarzeń. Jeśli nie ma opublikowanej wersji, żądanie jest natychmiast odrzucane; zdarzenie nie trafia do kolejki ani nie jest zapisywane na później. Przykłady w edytorze mogą odzwierciedlać zmiany w wersji roboczej, więc opublikuj je przed wysłaniem danych, które na nich polegają.

## Skopiuj URL i wyślij zdarzenie

Użyj **Copy request**, aby uzyskać polecenie cURL zawierające URL, nagłówki i przykładowe ciało żądania. Zastąp przykładowe wartości danymi ze swojej aplikacji.

URL zawiera identyfikatory obszaru roboczego i automatyzacji:

```text
POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>
```

Użyj pełnego URL skopiowanego z dashboardu. Nie potrzebujesz nagłówka `X-Workspace-Id`. Bieżąca opcja uwierzytelniania to **No authentication**: każdy, kto ma ten URL, może wysyłać zdarzenia. Przechowuj go w konfiguracji serwera.

Dla automatyzacji skonfigurowanej na `order.created` ustaw `AUTOMATION_EVENT_URL` na skopiowany URL i wyślij:

```bash
curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'
```

Ustaw `type` na skonfigurowaną nazwę zdarzenia, a `data` na obiekt odpowiadający polom zdarzenia. Możesz też podać `occurred_at` jako znacznik czasu RFC 3339; domyślnie przyjmuje czas nadejścia zdarzenia.

Odpowiedź `202 Accepted` z `status: "queued"` potwierdza, że zdarzenie trafiło do kolejki. Bird generuje identyfikator zdarzenia i zwraca go jako `event_id`. Otwórz kartę **Runs** automatyzacji, aby sprawdzić wykonanie. Przyjęcie do kolejki nie potwierdza, że zdarzenie pasowało do wyzwalacza ani że przebieg się rozpoczął.

Możesz też użyć **Send event…** w dashboardzie, aby przesłać przykład bez terminala. Wysyła to rzeczywiste zdarzenie.

## Kontynuuj przebieg oczekujący na zdarzenie

Krok oczekiwania korzysta z tego samego URL automatyzacji co wyzwalacz. Nazwa zdarzenia i `subject_key` identyfikują, co się wydarzyło i który przebieg powinien je otrzymać.

1. W **Automation settings** włącz **Skip overlapping runs** i **Use a business key**. Ustaw **Business key** na wartość identyfikującą zamówienie, fakturę lub inny obiekt. Dla przykładu z zamówieniem użyj wyrażenia `trigger.data.data.order_id`.
2. Dodaj **Wait for application event** i skonfiguruj nazwę zdarzenia, pola zdarzenia oraz limit czasu. Na przykład czekaj na `order.paid` z polem tekstowym `payment_id`.
3. Opublikuj, wyślij zdarzenie startowe i poczekaj, aż jego przebieg pojawi się w zakładce **Runs**.
4. Wyślij zdarzenie kontynuujące na ten sam URL, z `subject_key` równym kluczowi biznesowemu przebiegu:

```json
{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}
```

`subject_key` to wartość klucza biznesowego, na przykład `order_123`; to nie jest identyfikator zdarzenia ani identyfikator uruchomienia. Rozwinięty widok połączenia w kroku oczekiwania zawiera wskazówki dotyczące skonfigurowanego klucza.

Pasujące zdarzenie może zostać przechwycone po rozpoczęciu przebiegu, nawet zanim dotrze on do kroku oczekiwania. Zdarzenia przetworzone przed istnieniem pasującego przebiegu nie są zapisywane dla przyszłego przebiegu. Oczekiwanie z filtrem jest kontynuowane tylko wtedy, gdy pola zdarzenia i filtr jednocześnie pasują. Przebieg podąża ścieżką limitu czasu, jeśli przed upływem terminu nie zostanie przetworzone żadne kwalifikujące się zdarzenie.

Reguły anulowania w **Automation settings** również korzystają z tego URL. Reguła może obejmować wszystkie aktywne przebiegi automatyzacji lub przebieg pasujący do `subject_key`. Skonfiguruj filtr, aby zawęzić, które przebiegi są anulowane. Anulowanie nie może cofnąć akcji, która już została wykonana.

## Opublikowane wersje i wstrzymane automatyzacje

Nowe przebiegi korzystają z wersji aktywnej w momencie przetwarzania zdarzenia. Istniejące przebiegi zachowują swoją pierwotną wersję, w tym pola zdarzenia i warunki oczekiwania. Opublikowanie zmienionego formatu zdarzenia nie aktualizuje przebiegów, które już się rozpoczęły.

Wstrzymanie opublikowanej automatyzacji zatrzymuje nowe przebiegi. Zdarzenia nadal mogą kontynuować lub anulować istniejące przebiegi, gdy automatyzacja jest wstrzymana.

## Obsługa dostarczania i ponawiania

Zdarzenia są przetwarzane asynchronicznie i mogą być ponawiane lub przetwarzane w innej kolejności. Poczekaj, aż przebieg startowy zaistnieje, zanim wyślesz zdarzenie kontynuujące. `occurred_at` zdarzenia nie kontroluje kolejności przetwarzania, nie wydłuża oczekiwania ani nie zapobiega przekroczeniu limitu czasu.

Ochrona przed ponownym przetworzeniem jest ograniczona czasowo. Jeśli rekordy ponowień wygasną lub zostaną utracone, zdarzenie może zostać przetworzone ponownie, potencjalnie względem nowszej wersji lub innego aktywnego przebiegu. Zaprojektuj aplikację tak, aby tolerowała zduplikowane zdarzenia.

Aby włączyć ochronę przed powtórzeniami, podaj `Idempotency-Key` przy pierwszej próbie, a następnie użyj go ponownie z tym samym adresem URL i niezmienioną treścią żądania przy kolejnych próbach. Dla każdego nowego żądania użyj nowego klucza. Powtórzone żądanie zwraca ten sam `event_id`. [Przewodnik po idempotentności](/docs/guides/idempotency) opisuje ograniczone okno powtórzeń i odpowiedzi dotyczące konfliktów.

## Rozwiązywanie problemów ze zdarzeniem

- **Żądanie zwraca 4xx:** Sprawdź szczegóły błędu w odpowiedzi, URL oraz wymagane pola `type` i obiekt `data`. Wyślij `Content-Type: application/json`. Całe ciało żądania musi mieścić się w 25 KB (25 000 bajtów); większe ciała zwracają `413`.
- **Automatyzacja nie została opublikowana:** Opublikuj ją przed wysłaniem zdarzenia. Odrzucone zdarzenie nie jest zachowywane; wyślij nowe żądanie po opublikowaniu.
- **Żądanie zwraca 202, ale żaden przebieg się nie uruchamia:** Sprawdź, czy automatyzacja jest aktywna, nazwa zdarzenia pasuje do jej wyzwalacza, a dane odpowiadają opublikowanym polom zdarzenia. Ochrona przed nakładaniem się może pominąć nowy przebieg, gdy inny jest aktywny. Sprawdź też [miesięczny limit przebiegów](/docs/guides/automations/runs#early-access-run-allowance); uruchomienia pominięte po osiągnięciu limitu nie są kolejkowane na następny miesiąc.
- **Przebieg zatrzymał się na kroku oczekiwania:** Sprawdź nazwę zdarzenia, dokładny klucz biznesowy, pola danych, filtr i limit czasu. Użyj formatu zdarzenia z pierwotnej opublikowanej wersji przebiegu.
- **Ponowienie zwraca konflikt:** Ponów żądanie z oryginalnym kluczem i niezmienionym żądaniem. Jeśli chcesz wysłać inne zdarzenie, użyj nowego klucza.

Koperta żądania jest sprawdzana przed dodaniem do kolejki. Dane zdarzenia są sprawdzane względem wyzwalacza, oczekiwania i reguł anulowania podczas przetwarzania, więc zdarzenie w kolejce może nie pasować do żadnego z nich.

## Następne kroki

- [Otwórz **Automations**](https://bird.com/dashboard/w/automations), aby skonfigurować i opublikować workflow.
- [Obsługuj idempotentne ponawianie](/docs/guides/idempotency) w swojej aplikacji.
- [Czekaj na zdarzenie](/docs/guides/automations/waits) w działającym workflow.
- [Przeglądaj przewodniki Automations](/docs/guides/automations).

## Related resources

- [Preview your first automation](/docs/get-started/automations) (docs)