przypominamy-com Linki API

openapi: 3.2.0
info:
  title: Przypominamy Com Linki API
  version: 2.3.0
  contact:
    name: Wsparcie Przypominamy.com
    email: support@przypominamy.com
    url: https://przypominamy.com/api
  license:
    name: Proprietary
    url: https://przypominamy.com/regulamin
  termsOfService: https://przypominamy.com/regulamin
  x-audience: Polskie małe i średnie firmy integrujące SMS w CRM, e-commerce, aplikacjach 2FA, systemach umawiania wizyt i windykacji.
  x-llm-summary: 'Przypominamy.com to polskie REST API do wysyłki SMS. Jeden endpoint POST /v1/messages wysyła do jednego lub do 500 odbiorców (pole to: string, tablica albo "group:<nazwa>" - grupa kontaktów), z polami text (placeholdery {{imie}}, {{nazwisko}}, {{email}}, pola własne, {{opt_out}} = osobisty link wypisu), from (nadpis), send_at (ISO 8601, do 90 dni), send_window ("08:00-20:00", czas polski), expires_at (15 min – 72 h), reference. Zamiast text: template_id (szablon z GET/POST /v1/templates, {{klucz}} z params); priority: true = SMS priorytetowy, osobna kolejka, cena ×2. GET /v1/numbers/{msisdn}/lookup = HLR (status active/inactive/invalid/unknown, sieć; 0,05 zł, wynik z 24 h bez opłaty). DELETE /v1/messages/{id} anuluje zaplanowaną wysyłkę (status cancelled, zwrot kosztu). Historia: GET /v1/messages (cursor, filtry status/reference/to) i GET /v1/messages/{id}. Konto: GET /v1/account (saldo w groszach, cena za część, scopes, send_window, inbound_number, inbound_prefix), PATCH /v1/account (sender_name, send_window, inbound_prefix), GET /v1/senders, PUT /v1/account/webhook. Śledzone linki: {{link:https://…}} w text (do 2 adresów) = krótki link api.przypominamy.com/l/<token> per odbiorca z licznikiem kliknięć; GET /v1/messages/{id} zwraca links[], GET /v1/links (message_id, clicked=true) i GET /v1/links/{token} (click_log), webhook link.clicked przy pierwszym kliknięciu; bez dopłaty. Odbiór odpowiedzi (2-way) na życzenie, po uruchomieniu numeru odbiorczego w usłudze (do tego czasu inbound_number = null, lista pusta): odpowiedź ze słowem kluczowym klienta (inbound_prefix) albo od numeru, do którego klient pisał w ciągu 30 dni, trafia na GET /v1/inbound (from, since, unread, mark_read, cursor; pola id, from, to, text, reply_to, matched_by prefix|last_message, received_at, read_at) i GET /v1/inbound/{id}; webhook message.received z data.inbound i data.opt_out; STOP/WYPISZ/NIE = numer na czarną listę. Czarna lista: GET/POST /v1/blacklist, DELETE /v1/blacklist/{msisdn}; numery z listy dostają status rejected bez opłaty. Kontakty i grupy: GET/POST /v1/contacts, GET/PATCH/DELETE /v1/contacts/{id}, GET/POST /v1/groups, GET/PATCH/DELETE /v1/groups/{id}, POST /v1/groups/{id}/contacts, DELETE /v1/groups/{id}/contacts/{contactId}. Autoryzacja Bearer pk_live_… z zakresami send/read/manage (403 forbidden bez zakresu); klucz z panelu app.przypominamy.com/keys. Webhooki message.sent/delivered/undelivered/failed/expired, message.received i link.clicked podpisane HMAC-SHA256 w nagłówku X-Przypominamy-Signature (t=<unix>,v1=<hex>, podpis nad ''<t>.<body>'', tolerancja 300 s). Idempotency-Key. Błędy jako {error:{code,message,param},request_id}. Prepaid (domyślnie; billing_mode w GET /v1/account), saldo w groszach, 402 przy braku środków, 120 żądań/min. Postpaid na życzenie po weryfikacji: zestawienie miesięczne 1. dnia miesiąca, 14 dni na przelew, po terminie 402 do zaksięgowania wpłaty.'
  x-logo:
    url: https://przypominamy.com/przypominamy-logo.png
    altText: Przypominamy.com
  description: 'Operations tagged Linki across 2 of this provider''s published API definitions: openapi.json, przypominamy-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.przypominamy.com
  description: Produkcja
security:
- bearerAuth: []
tags:
- name: Linki
  description: Śledzone linki {{link:…}} z licznikiem kliknięć
paths:
  /v1/links:
    get:
      tags:
      - Linki
      summary: Śledzone linki i kliknięcia
      operationId: listLinks
      description: 'Linki utworzone z placeholdera `{{link:https://…}}` - jeden na parę (odbiorca, adres) - z licznikami kliknięć, od najnowszych. `totals` podsumowuje zwróconą stronę: liczba linków, ile z nich kliknięto choć raz, łączna liczba kliknięć. Wymaga zakresu `read`.'
      parameters:
      - name: message_id
        in: query
        schema:
          type: string
        description: Tylko linki z tej wiadomości (`msg_…`)
      - name: clicked
        in: query
        schema:
          type: boolean
        description: '`true` = tylko kliknięte'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Lista linków z podsumowaniem
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrackedLink'
                  totals:
                    type: object
                    properties:
                      links:
                        type: integer
                      clicked:
                        type: integer
                        description: Linki kliknięte co najmniej raz
                      clicks:
                        type: integer
                        description: Suma kliknięć
              example:
                data:
                - token: k3Jd9sQz
                  short_url: https://api.przypominamy.com/l/k3Jd9sQz
                  url: https://firma.pl/wizyta?id=7
                  message_id: msg_qY08hZ2mmDXAazdRTytS
                  to: '+48600100200'
                  clicks: 2
                  first_click_at: '2026-09-08T07:15:02.000Z'
                  last_click_at: '2026-09-08T09:40:17.000Z'
                  created_at: '2026-09-08T07:11:04.000Z'
                - token: Qz8Lm2Xa
                  short_url: https://api.przypominamy.com/l/Qz8Lm2Xa
                  url: https://firma.pl/wizyta?id=7
                  message_id: msg_b…
                  to: '+48600100201'
                  clicks: 0
                  first_click_at: null
                  last_click_at: null
                  created_at: '2026-09-08T07:11:04.000Z'
                totals:
                  links: 2
                  clicked: 1
                  clicks: 2
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-codeSamples:
      - lang: curl
        source: "curl \"https://api.przypominamy.com/v1/links?message_id=msg_qY08hZ2mmDXAazdRTytS\" \\\n  -H \"Authorization: Bearer $PRZYPOMINAMY_API_KEY\""
      - lang: Python
        source: "import requests\n\nr = requests.get(\n    \"https://api.przypominamy.com/v1/links\",\n    params={\"clicked\": \"true\"},\n    headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n    timeout=15,\n)\nlinks = r.json()\nprint(links[\"totals\"])  # {'links': 2, 'clicked': 1, 'clicks': 2}\nfor l in links[\"data\"]:\n    print(l[\"to\"], l[\"clicks\"], l[\"first_click_at\"])"
    servers:
    - url: https://api.przypominamy.com
      description: Produkcja
  /v1/links/{token}:
    get:
      tags:
      - Linki
      summary: Pobierz link z historią kliknięć
      operationId: getLink
      description: Jeden śledzony link wraz z `click_log` - do 50 ostatnich kliknięć (czas i `user_agent`; adres IP nie jest zwracany). Wymaga zakresu `read`.
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        example: k3Jd9sQz
      responses:
        '200':
          description: Link
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TrackedLink'
                - type: object
                  properties:
                    click_log:
                      type: array
                      items:
                        type: object
                        properties:
                          clicked_at:
                            type: string
                            format: date-time
                          user_agent:
                            type:
                            - string
                            - 'null'
              example:
                token: k3Jd9sQz
                short_url: https://api.przypominamy.com/l/k3Jd9sQz
                url: https://firma.pl/wizyta?id=7
                message_id: msg_qY08hZ2mmDXAazdRTytS
                to: '+48600100200'
                clicks: 2
                first_click_at: '2026-09-08T07:15:02.000Z'
                last_click_at: '2026-09-08T09:40:17.000Z'
                created_at: '2026-09-08T07:11:04.000Z'
                click_log:
                - clicked_at: '2026-09-08T09:40:17.000Z'
                  user_agent: Mozilla/5.0 (iPhone; CPU iPhone OS 19_0 like Mac OS X) …
                - clicked_at: '2026-09-08T07:15:02.000Z'
                  user_agent: Mozilla/5.0 (Linux; Android 16) …
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.przypominamy.com
      description: Produkcja
  /l/{token}:
    get:
      tags:
      - Linki
      summary: Przekierowanie śledzonego linku
      operationId: linkRedirect
      security: []
      description: Publiczny adres, który odbiorca dostaje w SMS-ie w miejsce `{{link:…}}`. Zlicza kliknięcie (licznik, czas, `user_agent`, skrót IP), przy pierwszym kliknięciu wysyła webhook `link.clicked`, i przekierowuje 302 na docelowy adres. Nieznany token = 404 „Link nieaktywny”. Nie wywołuj tego adresu z własnego kodu - każde wejście liczy się jako kliknięcie.
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        example: k3Jd9sQz
      responses:
        '302':
          description: Przekierowanie na docelowy adres
          headers:
            Location:
              schema:
                type: string
                format: uri
              example: https://firma.pl/wizyta?id=7
        '404':
          description: Link nieaktywny
          content:
            text/plain:
              schema:
                type: string
    servers:
    - url: https://api.przypominamy.com
      description: Produkcja
components:
  schemas:
    TrackedLink:
      type: object
      description: Śledzony link utworzony z `{{link:https://…}}` - jeden na parę (odbiorca, adres).
      properties:
        token:
          type: string
          description: 8 znaków, część adresu `/l/{token}`
          example: k3Jd9sQz
        short_url:
          type: string
          format: uri
          description: Pełny krótki adres; w SMS-ie idzie bez `https://`, żeby oszczędzić znaki
          example: https://api.przypominamy.com/l/k3Jd9sQz
        url:
          type: string
          format: uri
          description: Adres docelowy z placeholdera
          example: https://firma.pl/wizyta?id=7
        message_id:
          type:
          - string
          - 'null'
          example: msg_qY08hZ2mmDXAazdRTytS
        to:
          type:
          - string
          - 'null'
          description: Odbiorca, który dostał ten link
          example: '+48600100200'
        clicks:
          type: integer
          example: 2
        first_click_at:
          type:
          - string
          - 'null'
          format: date-time
        last_click_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - not_found
              - invalid_request
              - insufficient_funds
              - rate_limited
              - idempotency_conflict
              - provider_error
              - internal_error
            message:
              type: string
            param:
              type: string
              description: Pole żądania, którego dotyczy błąd (jeśli dotyczy)
        request_id:
          type: string
          example: req_DbIaEbKi5pbRgjCV
  responses:
    NotFound:
      description: Nie znaleziono
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Brak lub nieprawidłowy klucz API
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Nieprawidłowy klucz API
            request_id: req_…
    Forbidden:
      description: Klucz bez wymaganego zakresu (albo konto zawieszone / testowe wysyła na niezweryfikowany numer)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: Ten klucz API nie ma zakresu "send". Wygeneruj klucz z odpowiednim zakresem w panelu (app.przypominamy.com/keys).
            request_id: req_…
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: pk_live_…
      description: 'Klucz API z panelu app.przypominamy.com/keys (`pk_live_…` lub `pk_test_…`). Klucz ma zakresy: `send` (wysyłka i anulowanie), `read` (odczyt historii, raportów, konta, nadpisów, czarnej listy, kontaktów i grup, odpowiedzi 2-way i śledzonych linków), `manage` (ustawienia konta, webhook, zapis czarnej listy, kontaktów i grup). Brak zakresu = HTTP 403 `forbidden`. Klucze sprzed wprowadzenia zakresów mają wszystkie trzy.'
x-refined-from:
- openapi.json
- przypominamy-com-openapi.json