# API Integration Specification Template

Source: https://nerix.ai/templates/api-integration-specification

Specify how two systems connect: what data moves, how it is secured, how errors are handled and who owns it.

## Fill it in and preview

You are signed in. Fill it in your workspace and it is kept as a document you can send, share and have signed. [Open in your workspace](https://app.nerix.ai/documents/templates/api-integration-specification)

### API integration specification

**Integration:** Shop orders to accounting **Version:** 1.0 **Written by:** Hamza Idrissi **Date:** 5 April 2029

## 1. Purpose

Send each paid web shop order to the accounting system as a sales invoice, so finance does not retype it.

## 2. Systems

- **Sends data:** Web shop (API v2)

- **Receives data:** Accounting system (REST API)

## 3. Data flow

1. A customer pays for an order. 2. The shop sends a webhook to the integration service. 3. The service turns the order into an invoice and calls the accounting API. 4. The accounting system returns an invoice number, which the service saves on the order.

## 4. Endpoints and messages

| Method and path | What it does | Main fields | What it returns |

| POST /invoices | Create an invoice | Body: customer, lines, tax, total | Returns: invoice id and number |

| GET /customers?email= | Find a customer | Returns: customer id or empty | |

| POST /customers | Create a customer | Body: name, email, address | |

## 5. Field mapping

order.total_paid → invoice.total order.billing_email → customer.email order.items[].sku → line.product_code

## 6. Authentication and security

OAuth 2.0 client credentials. Tokens last one hour. Secrets are kept in the vault, never in code. All calls use HTTPS. Webhooks are signed and the signature is checked.

Personal data is sent only when needed, is not written to logs, and is covered by the privacy terms of both systems.

## 7. Errors and retries

Retry on 429 and 5xx up to 5 times with growing delays. Do not retry 4xx errors; log them and alert finance. Each invoice has a unique key so a retry cannot create a duplicate.

## 8. Limits and volumes

The accounting API allows 60 calls per minute. Expected 400 orders a day, up to 2,000 on sale days.

## 9. Testing

Use the accounting sandbox. Test a normal order, an order with a discount, a refund, a customer who already exists, and an API outage.

## 10. Owners and support

Owner: E-commerce team. Support: Hamza Idrissi. Escalation: the accounting vendor's support desk.

## 11. Changes and versioning

Either side gives 30 days' notice of a breaking change.

Templates are a careful starting point, not legal advice. Where the law matters, check what applies where you are.

IT and projects

## What this template is for

An API integration specification that describes how two systems connect: purpose, data flow, endpoints, authentication, errors, limits, testing and ownership.

It is free to fill in online, needs no account, and downloads as a Word document or a PDF. [See all IT and projects templates](https://nerix.ai/templates/it-projects)

IT and projects

## What you fill in

The form asks for 16 details. The document fills itself in as you type.

- ### Integration name For example: Shop orders to accounting
- ### Document version For example: 1.0
- ### Written by For example: Hamza Idrissi
- ### Date For example: 5 April 2029
- ### Purpose For example: Send each paid web shop order to the accounting system as a sales invoice, so finance does not retype it.
- ### System that sends data For example: Web shop (API v2)
- ### System that receives data For example: Accounting system (REST API)
- ### Data flow For example: 1. A customer pays for an order. 2. The shop sends a webhook to the integration service. 3. The service turns the order into an invoice and calls the accounting API. 4. The accounting system returns an invoice number, which the service saves on the order.
- ### Endpoints and messages One row for each endpoint or message. For example: POST /invoices | Create an invoice | Body: customer, lines, tax, total | Returns: invoice id and number GET /customers?email= | Find a customer | Returns: customer id or empty POST /customers | Create a customer | Body: name, email, address
- ### Field mapping Which field in the source goes to which field in the target. Say how values are converted. For example: order.total_paid → invoice.total order.billing_email → customer.email order.items[].sku → line.product_code
- ### Authentication and security For example: OAuth 2.0 client credentials. Tokens last one hour. Secrets are kept in the vault, never in code. All calls use HTTPS. Webhooks are signed and the signature is checked.
- ### Errors and retries For example: Retry on 429 and 5xx up to 5 times with growing delays. Do not retry 4xx errors; log them and alert finance. Each invoice has a unique key so a retry cannot create a duplicate.
- ### Limits and volumes (optional) optional For example: The accounting API allows 60 calls per minute. Expected 400 orders a day, up to 2,000 on sale days.
- ### Testing For example: Use the accounting sandbox. Test a normal order, an order with a discount, a refund, a customer who already exists, and an API outage.
- ### Owners and support For example: Owner: E-commerce team. Support: Hamza Idrissi. Escalation: the accounting vendor's support desk.
- ### Change and versioning (optional) optional For example: Either side gives 30 days' notice of a breaking change.

IT and projects

## What is inside

The parts of this document, in order.

- 1 1. Purpose
- 2 2. Systems
- 3 3. Data flow
- 4 4. Endpoints and messages
- 5 5. Field mapping
- 6 6. Authentication and security
- 7 7. Errors and retries
- 8 8. Limits and volumes
- 9 9. Testing
- 10 10. Owners and support
- 11 11. Changes and versioning

Templates

## How it works

- 01 ### Fill in Type your details in the form. The document fills itself in as you type; click any gap to jump to its field.
- 02 ### Check Read it through. Gaps you have not filled stay marked, so nothing goes out half done.
- 03 ### Download Save it as a Word document to edit further, or as a PDF to send or print.

### Make it yours with AI

Open it in the chat and ask for changes: shorter, firmer, another situation, another language.

[Adapt it with nerix](https://nerix.ai/try?template=api-integration-specification)

### Was this template helpful?

IT and projects

## Questions people ask

### What details does this template ask for?

The form asks for 16 details, starting with Integration name, Document version, Written by, Date, Purpose. 2 more are optional.

### Can I download this template as Word or PDF?

Yes. When you have filled in the form, save it as a Word document to keep editing, or as a PDF to send or print. It is free and needs no account.

### Is what I type sent anywhere?

No. What you type stays in your browser while you fill in the document. It only goes to nerix if you choose to open the template in the chat.

### Are these IT and project templates free?

Most are. Fill in and download them for free as Word or PDF, with no account. A few longer documents are premium: free to fill in, paid once to download, and marked with their price.

### Does a security policy make us secure?

No document does that alone. A policy helps when it matches what people really do, so keep it short, explain it to your team and review it every year.

### Is a project charter only for large projects?

No. A small project benefits too, because one page that names the goal, the limits and the decision maker prevents most arguments later.

Templates

## More in IT and projects

- [Architecture decision record Record a technical decision with its context, options, reasons and consequences, for the team to find later. IT and projects](https://nerix.ai/templates/architecture-decision-record)
- [Bring your own device policy Set the rules for using personal phones and laptops for work: security, privacy, support and leaving. IT and projects](https://nerix.ai/templates/byod-policy)
- [Bug report Report a software problem so a developer can repeat it, judge its impact and fix it. IT and projects](https://nerix.ai/templates/bug-report)
- [Change management plan Plan how people will be told, trained and supported through a big change, and how you will know it worked. IT and projects](https://nerix.ai/templates/change-management-plan)
- [Change request Ask for a change to a project or system, show its impact and record whether it is approved. IT and projects](https://nerix.ai/templates/change-request)
- [Cybersecurity awareness training record Keep proof that staff were trained on phishing, passwords and safe working: topics, attendance and results. IT and projects](https://nerix.ai/templates/cybersecurity-awareness-training-record)

[See all IT and projects templates](https://nerix.ai/templates/it-projects)

Templates

## More kinds of documents

Every category has its own page, so you can see all of its templates at once.

## Use it in nerix

### Use it in nerix

- [Templates](https://nerix.ai/product/templates)
- [Long tasks](https://nerix.ai/product/tasks)
- [Long documents](https://nerix.ai/product/long-documents)

### Learn more

- [How to Make a Document From a Template](https://nerix.ai/help/make-a-document-from-a-template)
- [IT and projects](https://nerix.ai/templates/it-projects)