Oferty z CRM przez Zapier, Make albo n8n

Beta. Jeśli w swoim koncie Proposals nie widzisz jeszcze Ustawienia → Integracje, napisz na support@proposals.co, a włączymy je dla Twojego zespołu.

Typowy scenariusz wygląda tak: szansa sprzedaży w CRM przechodzi na etap „Oferta”, automatyzacja wysyła notatki do Proposals, a gdy szkic jest gotowy, opiekun szansy dostaje wiadomość z linkiem do przejrzenia. Opiekun sprawdza ofertę i publikuje ją w panelu. Jeśli ufasz temu procesowi, publikować może też automatyzacja – pod warunkiem, że klucz ma zgodę na publikację i nic jej nie blokuje.

Nie ma jeszcze osobnej aplikacji w Zapierze ani w Make. Korzystasz z REST API przez ogólny krok HTTP (Webhooks by Zapier, moduł HTTP w Make, węzeł HTTP Request w n8n).

1. Utwórz klucz API

Administrator Proposals przechodzi do Ustawienia → Integracje → Klucze API i tworzy klucz:

• Nazwa: coś, co później rozpoznasz, na przykład Zapier – CRM.
• Uprawnienia: zostaw domyślne (odczyt marek, odczyt ofert, tworzenie i zmienianie). Publikację dodaj tylko wtedy, gdy automatyzacja ma publikować bez udziału człowieka.
• Skopiuj sekret (prp_live_…). Jest pokazywany tylko raz.

Zapisz go w miejscu na sekrety w narzędziu: w polu połączenia w Zapierze albo Make, a w n8n jako dane logowania typu Header Auth z nazwą Authorization i wartością Bearer prp_live_….

2. Sprawdź identyfikator marki (jeśli masz więcej niż jedną)

curl https://api.proposals.co/api/public/v1/brands \
  -H "Authorization: Bearer $PROPOSALS_API_KEY"

Zanotuj id marki, z której mają wychodzić oferty. Przy jednej marce możesz pominąć brand_id.

3. Utwórz ofertę

Ustawienia kroku HTTP:

• Metoda: POST
• Adres: https://api.proposals.co/api/public/v1/proposals
• Nagłówki:
  • Authorization: Bearer prp_live_…
  • Content-Type: application/json
  • Idempotency-Key: deal-{{deal_id}}-create
• Treść (JSON):

{
  "client": {
    "name": "{{company_name}}",
    "website": "{{company_website}}",
    "contact": { "name": "{{contact_name}}", "email": "{{contact_email}}" }
  },
  "context": "{{deal_notes}}",
  "brand_id": 42,
  "language": "pl",
  "pricing": {
    "amount": {{deal_amount}},
    "currency": "PLN",
    "tax_basis": "net",
    "billing": "one_off"
  },
  "external_reference": "{{deal_id}}"
}

Podepnij pola {{…}} pod pola z CRM. Jeśli szansa nie ma jeszcze uzgodnionej kwoty, wyślij "amount": null – oferta powie wtedy, że cena jest do ustalenia, i nigdy nie pokaże zgadniętej liczby.

Identyfikator szansy wstaw zarówno do Idempotency-Key, jak i do external_reference. Jeśli krok zostanie ponowiony albo ta sama szansa uruchomi scenariusz dwa razy, i tak powstanie jedna oferta: ponowienie zwróci pierwszą odpowiedź, a druga oferta dla tej samej szansy zostanie odrzucona z błędem 409 external_reference_exists (identyfikator istniejącej oferty jest w detail.params.proposal_id).

Odpowiedź to 202 z ofertą w statusie generating. Zapisz jej id.

4. Poczekaj na szkic

Pisanie trwa od 30 do 120 sekund. Wybierz to, co Twoje narzędzie obsługuje najlepiej:

• Zapier: dodaj Delay by Zapier na dwie minuty, a potem krok GET na https://api.proposals.co/api/public/v1/proposals/{{id}}. Jeśli status to nadal generating, dodaj drugie opóźnienie i sprawdź ponownie.
• Make: użyj modułu Repeater z modułem Sleep (30 sekund) i zapytaniem HTTP GET, a pętlę zakończ, gdy status przestanie być generating.
• n8n: węzeł Wait i węzeł IF sprawdzający status, który wraca do oczekiwania, dopóki status to generating. Pole next_poll_after_ms w odpowiedzi mówi, ile czekać.

Możesz też utworzyć ofertę z parametrem ?wait_seconds=50 w adresie. Wywołanie poczeka wtedy do 50 sekund i często od razu zwróci gotowy status. Może jednak nadal zwrócić generating, więc zostaw jedno opóźnione sprawdzenie na zapas.

5. Zareaguj na status

Dodaj filtr albo router na polu status:

panel_url wymaga zalogowania do Proposals, więc można go bezpiecznie wrzucić na wewnętrzny kanał. Nie wysyłaj go klientowi.

6. Opcjonalnie: publikacja z automatyzacji

Tylko z kluczem, który ma zgodę na publikację:

curl -X POST https://api.proposals.co/api/public/v1/proposals/$PROPOSAL_ID/publish \
  -H "Authorization: Bearer $PROPOSALS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deal-$DEAL_ID-publish" \
  -d '{"confirm": true}'

Odpowiedź zawiera public_url, czyli link dla klienta. Jeśli kontrola przed publikacją znajdzie blokadę, dostaniesz 422 preflight_blockers i nic nie zostanie opublikowane – tej blokady nie da się obejść. Każda publikacja przez integrację wysyła też powiadomienie właścicielowi oferty.

Publikacja niczego nie wysyła klientowi. Wstaw public_url do maila, który wysyła Twój CRM albo narzędzie pocztowe, a potem daj znać Proposals, że oferta poszła:

curl -X POST https://api.proposals.co/api/public/v1/proposals/$PROPOSAL_ID/mark-sent \
  -H "Authorization: Bearer $PROPOSALS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deal-$DEAL_ID-mark-sent" \
  -d '{}'

7. Opcjonalnie: reakcja klienta w CRM

Krok uruchamiany według harmonogramu (na przykład co godzinę) może odczytywać oferty otwartych szans przez GET /proposals/{id} i aktualizować CRM na podstawie pól status (opened, accepted) oraz engagement (first_opened_at, opens, accepted_at). Jeśli masz zapisany tylko identyfikator szansy, znajdziesz ofertę przez GET /proposals?external_reference={{deal_id}}. Webhooków jeszcze nie ma.

Limity, o których warto pamiętać

• Dziesięć nowych ofert na minutę na jeden klucz i najwyżej trzy oferty powstające jednocześnie w jednym zespole. Jeśli naraz przyjdzie dużo szans, odpowiedzi 429 powiedzą w nagłówku Retry-After, ile odczekać. Zapier, Make i n8n potrafią ponowić krok z opóźnieniem.
• Każda oferta liczy się w planie tak samo jak oferta z panelu.

Pełna lista endpointów i pól jest w referencji API, a znaczenie statusów, błędy i idempotencja – w przeglądzie.