Dokumentacja API Trimoji Resume

Ostatnia aktualizacja: 22 maja 2024

Niniejsze API umożliwia analizę (parsowanie) CV, tworzenie profili idealnych kandydatów (zwanych "Personi") oraz ocenę CV w stosunku do tych profili, aby zoptymalizować proces rekrutacji.

Konfiguracja

Konfiguracja zmiennych

Przed użyciem tego API należy skonfigurować następujące zmienne:

base_url: Podstawowy adres URL API (np. https://integration.trimoji.fr/api/v1/resume).
partner_token: Twój unikalny token uwierzytelniający partnera.
customer_token: Twój klucz API specyficzny dla klienta. Można go uzyskać z Panelu Trimoji, klikając przycisk "skopiuj mój klucz API".

Bezpieczeństwo

Uwierzytelnianie

Wszystkie żądania API muszą zawierać nagłówek (header) Authorization z Twoim partner_token.

Authorization: Twój_token_partnera_tutaj

Asynchroniczne

Mechanizm Callback (Webhook)

Wiele operacji, takich jak przesyłanie CV, jest asynchronicznych. Po zakończeniu przetwarzania Trimoji wysyła wyniki na podany przez Ciebie adres URL callback_url.

Callback w przypadku sukcesu

Dane wysyłane do Twojego callback_url po pomyślnym sparsowaniu będą miały następującą strukturę JSON:


{
  "metadatas": {
    "twoj_klucz": "niestandardowa_wartosc"
  },
  "resumeData": {
    "firstname": "string",
    "lastname": "string",
    "email": "string",
    "phone": "string",
    "sex": "string ('f', 'm', lub 'other')",
    "age": "integer | null",
    "introduction": "string | null",
    "address": "string | null",
    "lat": "number | null",
    "lon": "number | null",
    "processed_at": "datetime_string"
  },
  "experiences": [
    {
      "poste": "string",
      "company": "string",
      "size": "string | null ('AE', 'MIE', 'TPE', ...)",
      "start_date": "integer | null",
      "end_date": "integer | null",
      "duration": "integer | null",
      "tasks": ["string"]
    }
  ],
  "diplomas": [
    { "name": "string", "date": "integer | null" }
  ],
  "licenses": [
    { "name": "string", "desc": "string" }
  ],
  "languages": [
    { "name": "string (iso_code)", "level": "string" }
  ],
  "hobbies": ["string"],
  "telework": "string | null ('Flexible', 'Full time', ...)"
}

Callback w przypadku błędu

Jeśli przetwarzanie CV się nie powiedzie, zostanie wysłany callback zawierający szczegóły błędu i logi przetwarzania.


{
  "metadatas": {
    "uid": "user123",
    "source": "webapp"
  },
  "error": {
    "code": "PROCESSING_FAILED",
    "message": "Nie udało się wyodrębnić danych z dostarczonego pliku z powodu nieprawidłowego formatu."
  },
  "logs": [
    "[2024-05-21T10:00:05.123Z] [FILE_UPLOAD] [OK] Plik został pomyślnie przesłany.",
    "[2024-05-21T10:00:06.456Z] [PROCESS_STARTED] [OK] Rozpoczęto przetwarzanie.",
    "[2024-05-21T10:00:15.789Z] [DATA_STRUCTURE_GENERATION] [ERROR] Model AI zwrócił nieprawidłową strukturę."
  ]
}

Parsowanie CV

API Parsowania CV

1. Przesyłanie CV

Wyślij plik CV do asynchronicznego parsowania. Wyniki zostaną przesłane do callback_url.

POST /upload

Parametry Body (form-data)

Klucz	Typ	Opis
`customer_token` *	Tekst	Twój klucz API klienta.
`uploaded_file` *	Plik	Plik CV. Maksymalny rozmiar: 5MB. Dozwolone rozszerzenia: pdf, docx, png, jpg, jpeg, txt, webp, doc, rtf, pptx, otp, odp, odt.
`callback_url`	Tekst	Adres URL do otrzymywania wyników asynchronicznych.
`metadatas`	Tekst	Niestandardowy ciąg JSON do śledzenia.
`personi_id`	Tekst	Opcjonalny identyfikator Personi do powiązania CV.

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": {
        "resume_id": "6ff7d7fe-8e53-4ddf-b68a-f9d4658f5bc8"
    }
}

2. Pobieranie danych z CV

Pobierz sparsowane informacje z CV za pomocą jego resume_id.

GET /get/{customer_token}/{resume_id}

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": {
        "resumeData": {
            "firstname": "Lou",
            "lastname": "Pagès",
            "email": "[email protected]",
            "age": 22
        },
        "experiences": [ ... ],
        "diplomas": [ ... ]
    }
}

3. Pobieranie logów procesu

Pobierz logi przetwarzania dla konkretnego CV, pomocne w debugowaniu problemów z parsowaniem.

GET /get/{customer_token}/{resume_id}/logs

4. Usuwanie CV

Oznacza CV jako usunięte (usuwanie logiczne / soft delete).

DELETE /delete/{customer_token}/{resume_id}

Personi i punktacja

API Personi i Punktacja

„Personi” to idealny profil kandydata, zdefiniowany w formacie JSON, według którego można punktować CV.

1. Tworzenie Personi

Tworzy nowy profil idealnego kandydata. Możesz ręcznie podać szczegółowe kryteria lub użyć flag auto_weights i auto_keywords, aby pozwolić naszej SI wygenerować je na podstawie opisu stanowiska.

POST /personi/create

Parametry Body (JSON)

Klucz	Typ	Opis
`customer_token` *	String	Twój klucz API klienta.
`custom_id` *	String	Unikalny identyfikator Personi w Twoim systemie.
`position` *	String	Nazwa stanowiska.
`position_description` *	String	Szczegółowy opis roli.
`company_description` *	String	Opis firmy.
`sector` *	String	Sektor działalności stanowiska.
`company`	String	Nazwa firmy.
`diploma`	String	Wymagany minimalny poziom wykształcenia.
`telework`	String	Polityka pracy zdalnej. Wartości: `FLEXIBLE`, `FULLTIME`, `HYBRID`, `NEVER`, `OCCASIONAL`, `ONDEMAND`, `PARTTIME`, `ROTATION`.
`education_weight`	Number	Waga dla wyniku edukacji (0-100).
`experience_weight`	Number	Waga dla wyniku doświadczenia (0-100).
`skills_weight`	Number	Waga dla wyniku umiejętności (0-100).
`knowledge_weight`	Number	Waga dla wyniku wiedzy (0-100).
`keywords_weight`	Number	Waga dla wyniku słów kluczowych (0-100).
`geolocation`	Object	Kryteria lokalizacji: `{"address": "string", "radius": number}`. Promień w km (domyślnie 10).
`keywords`	Array	Ręczne słowa kluczowe: `[{"word": "string", "is_mandatory": boolean}]`.
`languages`	Array	Wymagania językowe: `[{"id": "iso_code", "level": "A1-C2"}]`. Poziomy: `A1, A2, B1, B2, C1, C2`.
`driving_licenses`	Array	Wymagane prawo jazdy, np. `["B", "C1"]`.
`auto_keywords`	Boolean	Ustaw na `true`, aby automatycznie wygenerować słowa kluczowe.
`auto_weights`	Boolean	Ustaw na `true`, aby automatycznie ustawić wagi.

Uwaga dotycząca wag: Jeśli używasz ręcznych wag, suma wszystkich pól *_weight musi być równa 100. Jeśli nie podano żadnych wag i auto_weights jest fałszywe, używany jest domyślny podział.

Przykłady zapytań

Automatyczne generowanie (SI)


{
    "custom_id": "MKT_ASSIST_001",
    "customer_token": "twoj_token",
    "position": "Junior Marketing Assistant",
    "position_description": "We are looking for...",
    "company_description": "Innovate Corp...",
    "sector": "Marketing",
    "auto_keywords": true,
    "auto_weights": true
}

Konfiguracja ręczna


{
    "custom_id": "SENIOR_DEV_002",
    "customer_token": "twoj_token",
    "position": "Senior Software Engineer",
    "position_description": "Seeking experienced...",
    "company": "Tech Solutions",
    "telework": "HYBRID",
    "education_weight": 10,
    "experience_weight": 40,
    "skills_weight": 20,
    "knowledge_weight": 10,
    "keywords_weight": 20,
    "keywords": [
        {"word": "Spring Boot", "is_mandatory": true}
    ],
    "geolocation": { "address": "Paris", "radius": 20 }
}

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": {
        "personi_id": "f8e1e2c3-6337-4644-9fbf-7e382d089e3d"
    }
}

2. Pobieranie wszystkich Personi

Pobierz listę wszystkich aktywnych Personi dla Twojego konta klienta. Jeśli wiele Personi ma ten sam custom_id, zwrócony zostanie tylko najnowszy.

GET /get/{customer_token}/personi/all

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "id": "f8e1e2c3...",
            "custom_id": "SENIOR_DEV_002",
            "name": "Senior Software Engineer Profile",
            "created_at": "2024-05-15T10:00:00.000Z"
        }
    ]
}

3. Pobieranie szczegółów Personi

Pobierz pełną konfigurację i szczegóły konkretnego Personi.

GET /get/{customer_token}/personi/details/{personi_id}

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": {
        "id": "5e0273f8-8cfd-4673-9a89-3f4c934d3391",
        "name": "Associate Product Manager | London",
        "matching_settings": {
            "weights": { "percent_experience": 44, "percent_hardskills": 19 },
            "languages": [ { "lang": "Angielski", "is_mandatory": true } ],
            "skills": [ { "skill": "active_listening", "value": 72 } ]
        }
    }
}

4. Punktowanie CV przeciwko Personi

Oblicza wynik konkretnego CV w stosunku do konkretnego Personi. Opcjonalnie zwraca wyjaśnienie wyniku w HTML.

POST /matching

Parametry Body (JSON)

Klucz	Typ	Opis
`resume_id` *	String	ID CV do oceny.
`personi_id` *	String lub Array	ID Personi(ów) do oceny.
`explainer`	String	Zwraca wyjaśnienie wyniku. Wartości: 'en', 'fr', 'es'.

Przykład odpowiedzi (Standard)


{
    "success": true,
    "message": "Success",
    "data": {
        "score": 60,
        "personi_name": "Programista w Trimoji"
    }
}

5. Punktowanie wszystkich CV przeciwko Personi

Oblicza wynik wszystkich aktywnych CV z Twojego konta w stosunku do jednego Personi, zwracając posortowaną listę najlepszych dopasowań.

POST /matchingAll

Parametry Body (JSON)

Klucz	Typ	Opis
`resume_id` *	String	ID CV do oceny.
`customer_token` *	String	Twój klucz API klienta.
`limit`	Integer	Maksymalna liczba wyników (domyślnie 100).

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "personi_id": "839d2953...",
            "personi_name": "SENIOR HR BUSINESS PARTNER...",
            "score": 100
        }
    ]
}

6. Punktowanie wszystkich CV przeciwko jednemu Personi

Oblicza wynik wszystkich aktywnych CV z Twojego konta w stosunku do jednego Personi.

POST /matchingAllResumes

Parametry Body (JSON)

Klucz	Typ	Opis
`customer_token` *	String	Twój klucz API klienta.
`personi_id` *	String	ID Personi do oceny.
`limit`	Integer	Maksymalna liczba CV do oceny.

Przykład odpowiedzi


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "resume_id": "ac4d685e-c8e4-474d-a92a-16758009fafe",
            "score": 100
        },
        {
            "resume_id": "602d7fc9-2b85-4064-9ae6-ad5be08d5bcb",
            "score": 95
        }
    ]
}

7. Usuwanie Personi

Oznacza Personi jako usunięte (usuwanie logiczne / soft delete).

DELETE /delete/{customer_token}/personi/{personi_id}

API Hardskills

Dokumentacja API Trimoji Resume

Konfiguracja zmiennych

Uwierzytelnianie

Mechanizm Callback (Webhook)

Callback w przypadku sukcesu

Callback w przypadku błędu

API Parsowania CV

1. Przesyłanie CV

Parametry Body (form-data)

2. Pobieranie danych z CV

3. Pobieranie logów procesu

4. Usuwanie CV

API Personi i Punktacja

1. Tworzenie Personi

Parametry Body (JSON)

Przykłady zapytań

2. Pobieranie wszystkich Personi

3. Pobieranie szczegółów Personi

4. Punktowanie CV przeciwko Personi

Parametry Body (JSON)

5. Punktowanie wszystkich CV przeciwko Personi

Parametry Body (JSON)

6. Punktowanie wszystkich CV przeciwko jednemu Personi

Parametry Body (JSON)

7. Usuwanie Personi