Purchase Order API

EDI 850 JSON Format API Documentation

Version 1.0.0

Base URL: https://api-edi.nationalpublicseating.com/

Overview

The Purchase Order API accepts purchase order data in EDI 850 JSON format via authenticated REST endpoints. Submit your purchase orders and receive immediate confirmation of receipt.

Authentication

The API supports two authentication methods: Bearer Token and Basic Auth. All authenticated endpoints accept either method.

Authentication Types by Endpoint

Endpoint Auth Type Notes
POST /api/v1/auth/token No Auth or Basic Auth Send username/password in body OR use Basic Auth header
POST /api/v1/files Bearer Token OR Basic Auth Use either authentication method
POST /api/v1/files/upload Bearer Token OR Basic Auth Use either authentication method
GET /health No Auth Public health check

Basic Authentication

Basic Auth sends your username and password in the Authorization header as a base64-encoded string.

Header Format:

Authorization: Basic base64(username:password)

Example (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files \
  -u "your_username:your_password" \
  -H "Content-Type: application/json" \
  -d @purchase-order.json

The -u flag automatically encodes credentials. Alternatively, you can encode them manually:

# Encode credentials (in terminal)
echo -n "your_username:your_password" | base64

# Use encoded value in header
curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files \
  -H "Authorization: Basic eW91cl91c2VybmFtZTp5b3VyX3Bhc3N3b3Jk" \
  -H "Content-Type: application/json" \
  -d @purchase-order.json
⚠️ Security:
  • Always use HTTPS: Never send credentials over plain HTTP
  • Choose one method: Use either Bearer Token OR Basic Auth per request, not both

Get Authentication Token

POST /api/v1/auth/token

Authentication: Optional - You can send credentials in the request body OR use Basic Auth header

Method 1: Request Body (JSON)

{
  "username": "your_username",
  "password": "your_password"
}
?? Important: Field names are case-sensitive. Use lowercase "username" and "password", not "Username" or "Password".

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Example (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Example (JavaScript):

const response = await fetch('https://api-edi.nationalpublicseating.com/api/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'your_username',
    password: 'your_password'
  })
});

const { token, expiresIn } = await response.json();

Method 2: Basic Auth Header

Instead of sending credentials in the body, you can use the Basic Auth header:

Example (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/auth/token \
  -u "your_username:your_password"

Example (JavaScript):

const username = 'your_username';
const password = 'your_password';
const encoded = btoa(`${username}:${password}`);

const response = await fetch('https://api-edi.nationalpublicseating.com/api/v1/auth/token', {
  method: 'POST',
  headers: { 
    'Authorization': `Basic ${encoded}`
  }
});

const { token, expiresIn } = await response.json();
Notes:
  • Tokens expire after 1 hour (3600 seconds)
  • Request a new token when the current one expires
  • Store the token securely
  • Field names are case-sensitive: Use "username" and "password" (lowercase)
  • Both methods work: You can use request body OR Basic Auth header

Submit Purchase Order

Method 1: Submit JSON Data

POST /api/v1/files

Authentication: Bearer Token OR Basic Auth (required)

Headers:

Standard Format (Recommended)

{
  "Id": "PO123456",
  "Version": 2020.1,
  "Timestamp": "2024-10-29T12:00:00Z",
  "POHeader": {
    "SoldTo": {
      "PartyId": "1100001001675",
      "Name": "Music Products Center",
      "Address": {
        "Attn": "BatchClient",
        "Address1": "Accounts Payable",
        "City": "Fort Wayne",
        "State": "IN",
        "PostalCode": "46818",
        "Country": "USA",
        "CountryCode": "US"
      }
    },
    "ShipTo": {
      "PartyId": "1200109211324",
      "Name": "Music Products Center AZDC",
      "Address": {
        "Address1": "16801 W Glendale Ave.",
        "City": "Litchfield Park",
        "State": "AZ",
        "PostalCode": "85340",
        "Country": "USA",
        "CountryCode": "US"
      }
    },
    "BuyerOrderId": "PO123456",
    "DateOrdered": "2024-10-29"
  },
  "PODetail": {
    "Items": [
      {
        "POLineNbr": 1,
        "BuyerItemId": "ITEM001",
        "Qty": 10,
        "UCValue": 99.99
      }
    ]
  }
}

Response (200 OK):

{
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "received",
  "timestamp": "2024-10-29T12:34:56.789Z"
}

Example with Bearer Token (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @purchase-order.json

Example with Basic Auth (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files \
  -u "your_username:your_password" \
  -H "Content-Type: application/json" \
  -d @purchase-order.json

Method 2: Upload JSON File

POST /api/v1/files/upload

Authentication: Bearer Token OR Basic Auth (required)

Headers:

Request:

Example with Bearer Token (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@purchase-order.json"

Example with Basic Auth (cURL):

curl -X POST https://api-edi.nationalpublicseating.com/api/v1/files/upload \
  -u "your_username:your_password" \
  -F "file=@purchase-order.json"

Health Check

GET /health

Response (200 OK):

{
  "status": "healthy",
  "timestamp": "2024-10-29T12:34:56.789Z"
}

Error Responses

All error responses follow this format:

{
  "error": "Error Type",
  "message": "Detailed error message",
  "timestamp": "2024-10-29T12:34:56.789Z"
}

HTTP Status Codes

Code Description Common Causes
200 Success Request processed successfully
400 Bad Request Missing fields, invalid JSON, schema validation failure
401 Unauthorized Missing token, invalid token, expired token
404 Not Found Invalid endpoint
500 Server Error File system error, unexpected exception

Rate Limits

Security Notes