This API allows for the submission of a follow-up plan (oppfølgingsplan) to NAV and/or the general practitioner. This API supports delegation, which means that you as the API consumer are acting on behalf of another company/end-user. The API also supports integration without delegation, which means that you are submitting a follow-up plan on behalf of your own company.
This README is primarily intended for "Lønns- og personalsystemer" (Payroll and HR Systems) that wants to integrate with NAV for submitting follow-up plans.
This step is not neccessary if you are acting on behalf of your own company.
To submit a follow-up plan on behalf of an employer, the employer must delegate rights to the API (scope) to you as an LPS system. This is done in Altinn. Please refer to the Altinn documentation. Please note that the employer can find our API by searching for "Oppfølgingsplan" in Altinn, in the menu for "Tilgang til programmeringsgrensesnitt - API".
In order to use the API, you need to have a Maskinporten client configured. Please refer to the Maskinporten documentation.
To retrieve a Maskinporten token, you need to send a POST request to the Maskinporten token
endpoint. Please refer to
the Maskinporten documentation for more
information.
- Scope to be used when requesting token:
nav:oppfolgingsplan/lps.write
If you want to verify that the integration works as expected, you can use the verify-integration endpoint. Please
refer to
the Swagger documentation for more information. Please
note that you will need to provide a valid Maskinporten token in the Authorization header.
To submit a follow-up plan, you need to send a POST request with the required payload. The API will return a unique uuid, which can be used later to check the sending status. Please refer to the Swagger documentation for more information. Please note that you will need to provide a valid Maskinporten token in the Authorization header.
To check the sending status of a follow-up plan, you need to send a GET request with the uuid you received when submitting the follow-up plan. Please refer to the Swagger documentation for more information. Please note that you will need to provide a valid Maskinporten token in the Authorization header.
Please refer to NAV's guide for testing delegable API's
Please refer to NAV's guide for testing API's
If you get an error, we will provide an ApiError object in the response body. An ApiError will contain the following fields:
- status: HttpStatusCode - type: ErrorType - message: String
| Status | Type | Example Message | Description |
|---|---|---|---|
| 400 | VALIDATION_ERROR | Invalid employee identification number | The employeeIdentificationNumber field does not match the required format (11 digits). |
| 400 | VALIDATION_ERROR | needsHelpFromNav cannot be true if sendPlanToNav is false | If you are not sending the plan to NAV, then you cannot ask from help from NAV |
| 400 | VALIDATION_ERROR | needsHelpFromNavDescription is obligatory if needsHelpFromNav is true | If you need help from NAV, then a description of what you need help with is mandatory. |
| 400 | VALIDATION_ERROR | employeeHasNotContributedToPlanDescription is mandatory if employeeHasContributedToPlan = false | If the employee has not contributed to the plan, then a description of why not is mandatory. |
| 400 | VALIDATION_ERROR | employeeHasNotContributedToPlanDescription should not be set if employeeHasContributedToPlan = true | If the employee has not contributed to the plan, then a description of why not should not be sent |
| 401 | AUTHENTICATION_ERROR | JWT is expired | The maskinporten-token is invalid. Please check message for the specific error. |
| 403 | NO_ACTIVE_SENT_SYKMELDING | No active sykmelding sent to employer | There is no active sykmelding, or the sykmelding is not sent to the employer |
| 403 | NO_ACTIVE_EMPLOYMENT | No active employment relationship found for given orgnumber | We could not find arbeidsforhold for the orgnumber provided by maskinporten |
| 404 | GENERAL_PRACTITIONER_NOT_FOUND | General practitioner was not found | The general practitioner was not found. Please ensure that it is correctly registered for the employee. |
| 404 | EMPLOYEE_NOT_FOUND | Could not find requested person in our systems | This employeeIdentificationNumber is not registered in NAV's systems. |
| 404 | FOLLOWUP_PLAN_NOT_FOUND | The follow-up plan with a given uuid was not found | The follow-up plan with a given uuid was not found. Only relevant for the status-endpoint. |
We have created a demo-app, which acts as an example of how you can implement the API. Here you will find relevant
input-fields with headers and descriptions for our API. When you fill out the demo-form, it will finally retrieve a
maskinporten-token on behalf of a random test-user, and submit this to our API on our test server. On the last page you
will be able to download a PDF, which looks similar to the PDF generated in production.
Please note that the demo app only showcases the fields relevant for the API. This means that you are not limited to
these fields (and functionality) in your own application! We encourage you to customize the form to fit your own needs.
For example could sykmeldingsgrad be a relevant field for leaders, however NAV does not need this information, and it
is therefore not included in the API.
Please write an email to team-esyfo@nav.no if you have questions about the API. Questions about maskinporten or Altinn must be directed to Digdir/Altinn.
🛠️🛠️ For NAV Developers 🛠️🛠️
- Installer og konfigurer Detect IDEA plugin for live kodeanalyse
- Installer Kotest IDEA plugin for å kjøre tester
Set target JVM version til 19
- Gå til dolly: https://dolly.ekstern.dev.nav.no/
- Lag en ny bruker med arbeidsforhold til det du satte opp for sluttbruker-org
- Gå til sykmeldingmock: https://teamsykmelding-mock.ansatt.dev.nav.no/sykmelding/opprett?was-old=true
- Mock en sykmelding for den ansatte du lagde i dolly
- Gå til ditt sykefravær: https://www.ekstern.dev.nav.no/syk/sykefravaer
- Send inn sykmeldingen til arbeidsgiver
| Description | Url |
|---|---|
| Testing library | https://kotest.io/ |
| Mocking library | https://mockk.io/ |
| Static code analysis | https://detekt.dev/ |
| Maskinporten | https://docs.digdir.no/docs/Maskinporten/maskinporten_summary.html |
| Swagger test | https://lps-oppfolgingsplan-mottak.ekstern.dev.nav.no/swagger |
| Demo application | https://demo.ekstern.dev.nav.no/oppfolgingsplan-lps |