API Documentation

Getting Started with the API

      The OncePDF API is really easy to use. It makes working with PDF files for people who make software. If you want to split documents split files make PDF files smaller or set up a system to handle documents automatically the OncePDF API is a great way to do these things in your software.
      The  OncePDF API uses a method that makes it easy ti add PDF features to your program with OncePDF API.You can use the API to handle PDF files easily. It helps you to make your software work well with PDF files. 
Who Should Use the OncePDF API?
      The OncePDF API is for people who make things like developers, new companies and business that use PDF documents every day. It is good for projects and big companies that need to work with documents automatically. Some people who use the OncePDF API are:       
  * People who make software that you can use online       
  * People who make apps for your phone or computer         
  * Big companies that make software       
   * Systems that help companies manage their customers and work   
   * Companies that make software         
   * People who make software for hospitals and doctors         
   * Systems that help with money and accounting         
   * Platforms that help with documents         
   * Systems that help companies manage their employees         
    * Government websites and public servicesIf you are making a website for
  your customers, a tool, for your company or a big system to manage documents the OncePDF API can help you with tasks that you have to do over and over with PDF documents. It is easy to get started with the OncePDF API.

Real-World Use Cases
           Many businesses have to deal with hundreds or even thousands of PDF documents every day. If they automate these tasks it can really cut down on the work and make their operations more efficent.
       Here are some examples of how this can be done :
                   1) Accounting software can take invoices and turn them into PDF documents that you can search through and then store them safely so you can look at them later. 
                   2) Human resource platforms can put together employment contracts, identity documents and onboarding forms into one PDF package for each employee.
                    3) Educational portals can make assignment submissions smaller so they do not take up much space but still keep the document quality good enough for instructors to use.
                     4) Healthcare applications can organize reports, prescriptions and laboratory results into PDF files that are easy to manage.
                     5) Legal firms can combine contracts supporting evidence and signed agreements into one document to get ready for a case.
                     6)  Insurance platforms can automatically put together claim forms. Supporting documents before they are reviewed.
                      7) Customer support systems can make PDF reports that you can download. These reports have service histories and communication records in them. PDF documents are really useful, in all these cases because they help businesses work efficiently with PDF documents.
Industries That Benefit from PDF Automation
         Document workflows are a part of many industries. The OncePDF API helps companies automate these processes so they can be fast, consistent and reliable.
         Some industries that really benefit from this include:
                       * Finance and Banking
                       * Accounting Services
                       * Education
                        * Healthcare
                        * Legal Services
                        * Insurance
                        * Human Resources
                        * Government Organizations
                         * Estate
                         * Logistics and Supply Chain
                         * Manufacturing
                         * E-commerce
                         * Customer Relationship Management (CRM)
                         * Enterprise Resource Planning (ERP)
                         * Software as a Service (SaaS)
      Lets look at an example of how this works. When you use the OncePDF API the process is pretty simple.Y
           1) your application uploads one or more PDF files for processing.
           2)The OncePDF API checks the request.
           3) Starts the selected operation like merging or splitting documents in a secure way.
            4)  If you have processing turned on your application gets updates through webhooks while the task is being done.
            5)When the processing is done the OncePDF API gives you the document or a secure link to download it.
             6) Then your application gives the completed PDF to the user. Stores it as part of your document workflow.

   This makes it easy for developers to add PDF features to their applications without having to deal with complicated processing logic. The OncePDF API helps applications give users secure and automated document experiences, with the OncePDF API.

Authentication

When you make API request you need to have an API key. This API key has to be in the Authorization header. Every single API request needs this API key to work properly. The API key is really important for API requests. 

Why API Keys Matter
   The API key is an important thing for keeping your integration safe. The API key helps the OncePDF API know what application is trying to use it. This way only applications that are allowed can use the services that the OncePDF API provides for working with documents.
   Using an API key also helps people see how the API is being used. It makes sure that no one uses the API much. This keeps the platform safe and working well.
   When you make a request, to the API, the API key that you used to make the request is always connected to it. This makes it easy to see what requests are being made and to figure out what is going wrong. The API key also helps with managing what your application is doing. 
Protecting Your API Key
  Your API key is like a password. Keep it safe because anyone who has it can make requests for your application.
  To keep your integration secure do the following:
  * Never put your API key in code that runs on the client-side like JavaScript or in source code that anyone can see.
  * Store API keys safely using server settings or special systems for managing secrets.
  * Do not save API keys in version control systems like Git.
  * Change your API keys from time to time as part of keeping your application secure.
  * Create API keys for different projects or environments if you can.
  * Make sure only the right people, on your team can access and manage API credentials.
By doing these things you make it harder for people to get access and make your application more secure in the long run. API keys are important so treat them with care. Your API key security is crucial.
Using Environment Variables
  Do not put your API keys into your application. It is better to store them as environment variables. This way is more secure it is easier to move your application to a place and you can handle different environments without changing your code.
           For example: ONCEPDF_API_KEY=your_api_key_here
Your application can read the value from the environment when it is running. This way you do not have to worry about your information being shared by mistake in your code setup files or public places. The ONCEPDF_API_KEY is safe because your application reads it from the environment.
Common Authentication Mistakes
   So you are having some problems with authentication. It is usually something that goes wrong. Here are some mistakes that people make:
   * They forget to put the Authorization header in.
   * They use the format for the header. They should use Bearer YOUR_API_KEY.
    * They copy an API key that does not work or has expired.
    * They put spaces or weird characters in the header.
    * They accidentally show the API key in the part of the application that users interact with.
     * They use the API key for the situation. For example they use a production key when they are testing.
If you check these things before you send requests you can avoid a lot of problems, with authentication. It will take you less time to figure out what is going wrong with the authentication. Authentication issues can be really frustrating so checking the authentication settings can really help with authentication.

Development vs. Production
   When we are making something we usually use test environments to check if the API integrations are working, to try out things and to see what is going wrong with the application. The test environments let us check how the requests are formatted if the authentication is working and if the error handling is good all without messing up the workflows.
   Before we put our application out for real we need to do a things:
     * Replace the test credentials with our real API key from the OncePDF API.
     * Keep the credentials safe by using environment variables or a secret management solution.
     * Make sure we have logging but do not show any sensitive authentication information.
     * Check that the error handling and retry logic are working for requests that fail.
     * Always keep an eye on how we are using the API and change the credentials when we need to.
  If we keep the development and production credentials separate it helps to reduce the security risks. Makes the deployment process more reliable.
  If we follow these practices, for authentication we can make a secure and reliable integration with the OncePDF API and we can protect our applications credentials so we can always use the PDF processing services without any problems. 

Endpoints

Webhooks

You can find out what is happening with your files without having to check all time. To do this you need to set up a link in your dashboard. This link is called Webhook URL. when you set this up you will get updates, about your file processing results away. 
Retry Behavior
   Occasionally a webhook delivery may not work because the server that is supposed to receive it is not available for a time gives an error message or there are problems with the internet connection. To make it more reliable we can try sending webhook notifications automatically if they do not go through.
   Webhook tries to send in these cases:
         * The server that is supposed to receive the webhook is not working.
         * There is a problem with the internet that stops the webhook from being delivered
         * The endpoint gives an HTTP error, like 4xx or 5xx.
         * The request takes long and runs out of time before getting a response.
  To prevent doing the task twice your application should consider webhook events as repeatable. This means checking the job_id before doing anything. If the same webhook event is received more, than once your application can safely ignore the events that have already been handled.
Webhook Timeout
      When you get a webhook notification your endpoint should respond fast.Do not do tasks right away when you receive a notification.
      Here is what you should do instead:
           * Receive the webhook notification.
           * Check if the request is valid.
           * Save the event in your system.
           * Send back an HTTP 200 response right away.
           * Process the document later, in the background.
    Responding quickly helps prevent delivery failures and reduces retries.This way your webhook endpoint works smoothly and efficiently.
Common Troubleshooting
  If webhook notifications are not arriving as expected, the following checks can help identify the issue.Webhook Not Received
  Possible causes include:
        1) Incorrect webhook URL
        2) Server not publicly accessible
        3) Network or firewall restrictions
        4) DNS configuration issues
Verify that your webhook endpoint is reachable from the internet and accepts HTTPS requests.
Duplicate Webhook
   EventsSometimes you might get notifications. This happens when the original delivery wasn't confirmed properly.
   Here are some things you can do:
       * Keep track of each job_id.
       * Ignore events that you have already handled.
       * Make sure your endpoint replies, with HTTP 200 OK away when it gets the event successfully.

Error Codes

We use HTTP response codes to figure out if an API request works or not. we want to know if the API request is successful or if it fails. So we use these HTTP response codes to tell us what happens with the API request.