Creating transaction

Przesyłanie transakcji

Transakcje przesyłane są z systemu zewnętrznego do Pergaminu. Na podstawie przekazanych danych, tworzone są dokumenty w Pergaminie.

Aby przesłać dane do Pergaminu za pomocą T-API należy wykorzystać request POST do endpointu /ext-api/v2/transactions oraz jedną z metod autentykacji opisaną w Authentication (np. Bearer token zawarty w nagłówku Authorization).

Przesyłane dane powinny mieć uporządkowaną strukturę, która będzie przekazywana w formie JSON-a.

W paylodzie powinny być przesłane informacje dotyczące pól uwzględnionych w typie danych - zgodnie z ich wymagalnością (polem required).

Każdy payload z danymi powinien zawierać:

transaction_data_stream - wskazujący na nazwę wykorzystywanego strumienia danych,
transaction_body - w którym będą ujęte wszystkie przesyłane dane, które w dalszej kolejności będą wykorzystane do uzupełnienia przygotowanych szablonów dokumentów.

Wykorzystując przykładowy typ danych:

name="__codelineno-0-1">data_type: header: type: object fields: TransactionId: type: string TransactionOwner: type: string Date: type: string TypeOfVehicle: type: string required: false YearOfProduction: type: string required: false MileageLimit: type: string required: false Address: type: string required: false ItemId: type: string ItemName: type: string Queue: type: queue required: false invoice: type: array items: type: object fields: InvoiceValue: type: decimal required: false Tax: type: integer required: false Queue: type: queue required: false statute: type: object fields: CustomerName: type: string required: true CarRegistrationNumber: type: string required: false Queue: type: queue required: false statement: type: array required: false items: type: object fields: Name: type: string Surname: type: string Identification: type: string required: false IdentificationSeries: type: string required: false SocialSecurityNumber: type: string required: false DateStatement: type: string required: false ClientAddress: type: string required: false Queue: type: queue required: false

można wysłać następujący payload:

curl --location 'https://ext-api.pergam.in/ext-api/v2/transactions' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'X-App-Locale: pl' \
--data-raw '{
    "transaction_data_stream": "LEASE_AGREEMENT",
    "transaction_name": "Nazwa ransakcji",
    "transaction_body": {
        "header": {
            "TransactionId": "id_transaction",
            "TransactionOwner": "[email protected]",
            "Date": "2023-05-17",
            "TypeOfVehicle": "car",
            "YearOfProduction": "2023",
            "MileageLimit": "2000",
            "Address": "ul. Mickiewicza 12, 06-400 Ciechanów",
            "ItemId": "1",
            "ItemName": "Volkswagen Arteon",
            "Queue": {
               "Signers": [
                        {
                            "Email": "[email protected]",
                            "SignMethod":"SMS",
                            "Step": 1
                        },
                        {
                            "Email": "[email protected]",
                            "SignMethod":"SMS",
                            "Step": 2
                        }
                    ]                
            }
    },
        "invoice": [
            {
                "InvoiceValue": "350000.01",
                "Tax": 23
            }
        ],
        "statute":
            {
                "CustomerName": "Name and suranem",
                "CarRegistrationNumber": "WP 12345"
            },
        "statement": [
            {
                "Name": "Edward",
                "Surname": "Kowalski",
                "Identification": "dowód osobisty",
                "IdentificationSeries": "APD 776655",
                "SocialSecurityNumber": "00000000000",
                "DateStatement": "2023-04-18",
                "ClientAddress": "ul. Pokrętna 54, 06-400 Ciechanów"
            }
        ]
    }
}'

Jeśli w typie danych, któryś z atrybutów jest tablicą, możliwe jest przesyłanie w payloadzie więcej danych odwołujących się do określonych pól, dzięki czemu z 1 szablonu powstanie więcej niż 1 dokument.

Przykład takiego typu danych wskazany jest powyżej. Natomiast przykład paylodu jest następujący:

curl --location 'https://ext-api.pergam.in/ext-api/v2/transactions' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'X-App-Locale: pl' \
--data-raw '{
    "transaction_data_stream": "LEASE_AGREEMENT",
    "transaction_name": "Nazwa ransakcji",
    "transaction_body": {
        "header": {
            "TransactionId": "id_transaction",
            "TransactionOwner": "[email protected]",
            "Date": "2023-05-17",
            "TypeOfVehicle": "car",
            "YearOfProduction": "2023",
            "MileageLimit": "2000",
            "Address": "ul. Mickiewicza 12, 06-400 Ciechanów",
            "ItemId": "1",
            "ItemName": "Volkswagen Arteon",
            "Queue": {
               "Signers": [
                        {
                            "Email": "[email protected]",
                            "SignMethod":"SMS",
                            "Step": 1
                        },
                        {
                            "Email": "[email protected]",
                            "SignMethod":"SMS",
                            "Step": 2
                        }
                    ]                
            }
    },
        "invoice": [
            {
                "InvoiceValue": "350000.01",
                "Tax": 23
            }
        ],
        "statute":
            {
                "CustomerName": "Name and suranem",
                "CarRegistrationNumber": "WP 12345"
            },
        "statement": [
            {
                "Name": "Edward",
                "Surname": "Kowalski",
                "Identification": "dowód osobisty",
                "IdentificationSeries": "APD 776655",
                "SocialSecurityNumber": "00000000000",
                "DateStatement": "2023-04-18",
                "ClientAddress": "ul. Pokrętna 54, 06-400 Ciechanów"
            },
            {
                "Name": "Marian",
                "Surname": "Nowakowski",
                "Identification": "dowód osobisty",
                "IdentificationSeries": "AAA 998877",
                "SocialSecurityNumber": "00000000001",
                "DateStatement": "2023-04-18",
                "ClientAddress": "ul. Polna 12, 06-400 Ciechanów"
            },
        ]
    }
}'

W odpowiedzi na przesłaną transakcję system zwróci identyfikator zadania, które zostało zakolejkowane. Możliwe jest odpytanie o status tego zadania poprzez wysłanie requestu GET do endpointa /ext-api/v2/jobs/{jobId}.

Dodatkowe pola w paylodzie

W paylodzie przesyłanych danych do Pergaminu mogą znajdować się dodatkowe pola:

transaction_name - określający dodatkową nazwę transakcji,
transaction_apply - którego wartość to apply lub apply_with_errors, a wartości te umożliwiają automatyczne aplikowanie transakcji. Wykorzystując wartość apply, dokumenty w ramach transakcji zostaną automatycznie utworzone tylko wtedy, gdy nie będzie w nich żadnych błędów, np. związanych z walidacją pól zmiennych. Wartość apply_with_errors pozwoli na automatyczne utworzenie dokumentów w transakcji nawet wtedy, gdy system napotka błędy.

Akceptowanie przesłanej transakcji

Po przesłaniu danych transakcyjnych do Pergaminu, niezbędne jest ich zaakceptowanie, aby utworzone zostały dokumenty. Można to zrobić za pośrednictwem requestu POST do endpointa /api/v2/organisations/{organisationV2}/data-streams/{dataStream}/transactions/{transactionV2}, gdzie:

organisationV2 - to identyfikator organizacji,
dataStream - to nazwa strumienia danych,
transactionV2 - to nazwa transakcji.

Korzystając z powyższego requestu należy w headerze uwzględnić również X-Transaction-Entry-Id, czyli identyfikator transakcji. Można go sprawdzić za pośrednictwem requestu GET /api/v2/organisations/{organisationV2}/transactions. Pobrana wtedy zostanie lista transakcji, a wśród danych widoczny będzie ich identyfikator.

Przykład:

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transaction_data_stream": "string",
      "transaction_id": "string",
      "transaction_name": "string",
      "status": {
        "code": -3,
        "message": "string",
        "invalid": true,
        "applied": true
      },
      "owner": {
        "id": 0,
        "name": "string",
        "surname": "string",
        "email": "[email protected]",
        "is_deleted": true
      },
      "created_at": "2023-05-18T08:19:53.224Z",
      "updated_at": "2023-05-18T08:19:53.224Z",
      "__links": {
        "some_action": {
          "rel": "some_action",
          "type": "POST",
          "href": "https://api.pergam.in/api/v2/some_action_path"
        }
      }
    }
  ],
  "__links": {
    "some_action": {
      "rel": "some_action",
      "type": "POST",
      "href": "https://api.pergam.in/api/v2/some_action_path"
    }
  },
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "per_page": 0,
    "path": "string"
  }
}

Walidacja danych w transakcjach

Transakcje, które są wysyłane do Pergaminu, przechodzą walidację. Polega ona na sprawdzeniu typów przesłanych danych, a także ich wymagalności.

Kod	Opis
-1	Zadanie oczekuje w kolejce i nie zostało jeszcze przetworzone
0	Dane zostały zwalidowane i są poprawne
1	Przesłane dane transakcji są niepoprawne (Błędy walidacji). Błędy walidacji mogą dotyczyć niepoprawnego typu atrybutu lub jego braku.
2	Niepoprawny strumień danych, należy do innej organizacji, nie istnieje lub przypisany jest do innego użytkownika technicznego.
3	Błąd mapowania. Wymagane pola do dokumentu nie zostały przesłane lub szablon mapuje na więcej niż jeden obiekt (nie licząc header). Zakładając, że w requescie dostajemy trzy obiekty header, pozycja-faktury, oferta, a szablon będzie chciał mapować z pozycja-faktury oraz oferta będzie powodować błąd niejednoznaczności mapowania. W przyszłości będzie można zaprojektować to tak, aby szablon mógł korzystać z kilku obiektów, lecz tylko jeden z nich będzie mógł być tablica lub pozostałe tablice mają taką samą długość, ponieważ tworząc kilka dokumentów z parametru, który jest tablica i odwołując się do innej tablicy, która może być różnej długości, może dojść do sytuacji, że nie będzie wiadomo, do którego dokładnie atrybutu mamy zmapować zmienną.

Listowanie transakcji

Po utworzeniu transakcji widoczne są one na liście. Zobaczyć ją można za pośrednictwem requestu GET wysyłanego do endpointa /api/v2/organisations/{organisationV2}/transactions.

Odpowiedź stanowić będzie listę wszystkich transakcji.

Przykład:

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transaction_data_stream": "string",
      "transaction_id": "string",
      "transaction_name": "string",
      "status": {
        "code": -3,
        "message": "string",
        "invalid": true,
        "applied": true
      },
      "owner": {
        "id": 0,
        "name": "string",
        "surname": "string",
        "email": "[email protected]",
        "is_deleted": true
      },
      "created_at": "2023-05-18T09:04:32.864Z",
      "updated_at": "2023-05-18T09:04:32.864Z",
      "__links": {
        "some_action": {
          "rel": "some_action",
          "type": "POST",
          "href": "https://api.pergam.in/api/v2/some_action_path"
        }
      }
    }
  ],
  "__links": {
    "some_action": {
      "rel": "some_action",
      "type": "POST",
      "href": "https://api.pergam.in/api/v2/some_action_path"
    }
  },
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "per_page": 0,
    "path": "string"
  }
}

Lista transakcji może być filtrowana po następujących parametrach:

transaction_id_or_name - identyfikator transakcji lub jej nazwa,
transaction_status - statusie transakcji, w ramach którego dostępne są warianty: processing, ok, error,
transaction_owner_ids - identyfikatorze właściciela transakcji,

Dodatkowo możliwe jest sortowanie listy transakcji poprzez wykorzystanie parametrów: - per_page - zmiana ilości transakcji wyświetlanych na 1 stronie, - sort_dir - sposobie sortowania (asc, desc).

Typy danych i strumienie danych w powstałych transakcjach

Podczas tworzenia transakcji typ danych oraz strumień są kopiowane. Dzięki temu możliwe jest ich modyfikowanie w zakresie konkretnej transakcji, niezależnie od ujęcia globalnego. Modyfikacja strumienia danych i typu danych w ramach istniejącej transakcji daje szansę na poprawienie ewentualnych błędów, przy czym niezbędne będzie ponowne przesłanie danych do danej transakcji, aby została ona zaktualizowana.

Modyfikacja typu danych w istniejących transakcjach

Podgląd informacji zawartych w typie danych możliwy jest za pomocą requestu GET wysyłanego do endpointa /api/v2/organisations/{organisationV2}/data-streams/{dataStream}/transactions/{transactionV2}/data-type, gdzie:

organisationV2 - to identyfikator organizacji,
dataStream - to nazwa strumienia danych,
transactionV2 - to nazwa transakcji.

W odpowiedzi przekazany będzie typ danych w postaci YAML-a, jak na przykładzie:

{
  "data": {
    "name": "string",
    "yaml": "ZGF0YV90eXBlOgogIGhlYWRlcjoKICAgIHR5cGU6IG9iamVjdAogICAgZmllbGRzOgogICAgICBUcmFuc2FjdGlvbklkOgogICAgICAgIHR5cGU6IHN0cmluZwogICAgICBUcmFuc2FjdGlvbk93bmVyOgogICAgICAgIHR5cGU6IHN0cmluZwogICAgICBEb2N1bWVudF9EYXRlOgogICAgICAgIHR5cGU6IHN0cmluZwogICAgICBEb2N1bWVudFZhbHVlOgogICAgICAgIHR5cGU6IGRlY2ltYWwKICAgICAgICByZWY6IGRhdGFfdHlwZS5oZWFkZXIuQ3VycmVuY3kKICAgICAgQ3VycmVuY3k6CiAgICAgICAgdHlwZTogc3RyaW5nCiAgcG96eWNqZUZha3R1cnk6CiAgICB0eXBlOiBhcnJheQogICAgaXRlbXM6CiAgICAgIHR5cGU6IG9iamVjdAogICAgICBmaWVsZHM6CiAgICAgICAgSXRlbUlkOgogICAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgICByZXF1aXJlZDogZmFsc2UKICAgICAgICBJdGVtTmFtZToKICAgICAgICAgIHR5cGU6IHN0cmluZwogICAgICAgIEl0ZW1OZXRWYWx1ZToKICAgICAgICAgIHR5cGU6IGludGVnZXIKICAgICAgICBJdGVtVGF4UmF0ZToKICAgICAgICAgIHR5cGU6IGludGVnZXI=",
    "created_at": "2023-05-18T09:13:57.356Z",
    "updated_at": "2023-05-18T09:13:57.356Z",
    "__links": {
      "some_action": {
        "rel": "some_action",
        "type": "POST",
        "href": "https://api.pergam.in/api/v2/some_action_path"
      }
    }
  }
}

Modyfikowanie typu danych w istniejącej transakcji jest możliwe poprzez wysłanie requestu PATCH do endpointa /api/v2/organisations/{organisationV2}/data-streams/{dataStream}/transactions/{transactionV2}/data-type. Modyfikowany typ danych powinien być przesyłany w formie YAML-a.

Przykład:

{
  "yaml": "string"
}

Modyfikacja strumienia danych w istniejących transakcjach

Po przesłaniu transakcji T-API daje możliwość modyfikowania skopiowanego do niej strumienia danych. Szczegóły na temat strumienia danych w ramach konkretnej transakcji można uzyskać za pośrednictwem requestu GET wysyłanego do endpointa /api/v2/organisations/{organisationV2}/data-streams/{dataStream}/transactions/{transactionV2}/data-stream, gdzie:

organisationV2 - to identyfikator organizacji,
dataStream - to nazwa strumienia danych,
transactionV2 - to nazwa transakcji.

Modyfikację strumienia danych skopiowanego do konkretnej transakcji umożliwia request PATCH wysyłany do endpointa /api/v2/organisations/{organisationV2}/data-streams/{dataStream}/transactions/{transactionV2}/data-stream. Umożliwia on modyfikowanie:

identyfikatora szablonu,
referencji,
zewnętrznego id transakcji,
nazwy dokumentu,
opcji blokowania tworzenia dokumentu z danego szablonu,
ścieżki pliku w przypadku przesyłanych dokumentów PDF.

Przykładowy payload:

{
  "templates": [
    {
      "template_id": 0,
      "document_reference": "string",
      "document_external_id": "string",
      "document_content": "string",
      "is_blocked": true
    }
  ]
}