API Documentation

Welcome to the GECKO EDI API documentation. This guide will help you integrate EDI document management into your application with our RESTful API.

Get API Key

REST

RESTful API

Standard HTTP methods with JSON request and response bodies

Current Version

Stable API with semantic versioning and backward compatibility

TLS 1.2+

Secure

All requests encrypted with industry-standard security

Base URL

https://api.geckoedi.com/v1

All API endpoints are relative to this base URL. All requests must be made over HTTPS.

Authentication

The GECKO EDI API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Keep your API key secure

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or anywhere else.

Using your API key

All API requests must include your API key in the Authorization header as a Bearer token:

Example Requestbash

curl https://api.geckoedi.com/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response:

Error Responsejson

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Quick Start

1.Sign up for a GECKO EDI account
2.Navigate to the API Keys section in your Dashboard
3.Generate a new API key
4.Include the key in your request headers

API Endpoints

The GECKO EDI API provides endpoints for managing EDI documents, including creation, retrieval, validation, and status tracking.

POST/v1/documents

Create and send a new EDI document

Request Body

Example Requestjson

{
  "type": "EDI_850",
  "sender_id": "SENDER123",
  "receiver_id": "RECEIVER456",
  "data": {
    "purchase_order": {
      "po_number": "PO-2024-001",
      "date": "2024-01-15",
      "items": [
        {
          "line_number": 1,
          "product_id": "PROD-123",
          "quantity": 100,
          "unit_price": 25.50
        }
      ]
    }
  }
}

Response

201 Createdjson

{
  "id": "doc_1234567890",
  "type": "EDI_850",
  "status": "pending",
  "sender_id": "SENDER123",
  "receiver_id": "RECEIVER456",
  "created_at": "2024-01-15T10:30:00Z",
  "validation": {
    "passed": true,
    "errors": []
  }
}

Parameters

type *: EDI document type (e.g., EDI_850, EDI_810, EDI_856)
sender_id *: Sender identification code
receiver_id *: Receiver identification code
data *: Document payload matching the EDI type schema

GET/v1/documents

Retrieve a list of all EDI documents

Query Parameters

limit: Number of documents to return (default: 10, max: 100)
starting_after: Cursor for pagination (document ID)
status: Filter by status: pending, delivered, failed
type: Filter by EDI document type

Response

200 OKjson

{
  "data": [
    {
      "id": "doc_1234567890",
      "type": "EDI_850",
      "status": "delivered",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "doc_0987654321",
      "type": "EDI_810",
      "status": "pending",
      "created_at": "2024-01-14T15:20:00Z"
    }
  ],
  "has_more": false,
  "total": 2
}

GET/v1/documents/:id

Retrieve a specific EDI document by ID

Path Parameters

id *: The unique identifier of the document

Response

200 OKjson

{
  "id": "doc_1234567890",
  "type": "EDI_850",
  "status": "delivered",
  "sender_id": "SENDER123",
  "receiver_id": "RECEIVER456",
  "data": {
    "purchase_order": {
      "po_number": "PO-2024-001",
      "date": "2024-01-15",
      "items": [...]
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:31:23Z"
}

POST/v1/documents/validate

Validate an EDI document without sending it

Request Body

Example Requestjson

{
  "type": "EDI_850",
  "data": {
    "purchase_order": {
      "po_number": "PO-2024-001",
      "date": "2024-01-15"
    }
  }
}

Response

200 OKjson

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "field": "data.purchase_order.items",
      "message": "No items specified in purchase order"
    }
  ]
}

DELETE/v1/documents/:id

Delete a specific EDI document (only if status is 'pending' or 'failed')

Path Parameters

id *: The unique identifier of the document to delete

Note: Documents with status 'delivered' cannot be deleted. You'll receive a 403 Forbidden error if you attempt to delete a delivered document.

Error Codes

The GECKO EDI API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error with the provided information, and codes in the 5xx range indicate an error with our servers.

Error Response Format

All error responses follow a consistent JSON structure:

Error Responsejson

{
  "error": {
    "type": "validation_error",
    "message": "Invalid EDI document structure",
    "details": {
      "field": "data.purchase_order.po_number",
      "issue": "Required field missing"
    },
    "request_id": "req_1234567890"
  }
}

HTTP Status Codes

400

Bad Request

The request was malformed or invalid. Check the error details for specific issues.

validation_errorinvalid_request_error

401

Unauthorized

Authentication failed. Your API key is missing, invalid, or expired.

authentication_error

403

Forbidden

The API key doesn't have permission to perform the requested action.

permission_error

404

Not Found

The requested resource doesn't exist.

resource_not_found

409

Conflict

The request conflicts with the current state of the resource.

conflict_error

429

Too Many Requests

You've exceeded the rate limit. Please wait before making additional requests.

rate_limit_error

500

Internal Server Error

An unexpected error occurred on our end. Please try again later.

server_error

503

Service Unavailable

The service is temporarily unavailable. Please try again later.

service_unavailable

Best Practices

•Always check the HTTP status code to determine if the request succeeded
•Use the error type field to programmatically handle different error scenarios
•Store the request_id for debugging and support inquiries
•Implement exponential backoff for 429 and 5xx errors

Rate Limits

The GECKO EDI API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied per API key and vary based on your subscription tier.

Free

100 requests/hour

Burst: 20 requests/minute

✓Basic EDI documents
✓Standard validation

Popular

Professional

1,000 requests/hour

Burst: 100 requests/minute

✓All EDI document types
✓Advanced validation
✓Priority support

Enterprise

Custom limits

Burst: Custom burst limits

✓Unlimited documents
✓Custom integrations
✓Dedicated support
✓SLA guarantee

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

Response Headershttp

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705420800

X-RateLimit-Limit: The maximum number of requests allowed in the current time window
X-RateLimit-Remaining: The number of requests remaining in the current time window
X-RateLimit-Reset: Unix timestamp indicating when the rate limit will reset

Handling Rate Limit Errors

When you exceed your rate limit, you'll receive a 429 Too Many Requests response:

429 Too Many Requestsjson

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 60,
      "limit": 1000,
      "window": "3600"
    }
  }
}

Best Practices

•Monitor headers: Check X-RateLimit-Remaining to track your usage
•Implement backoff: Use exponential backoff when you receive 429 errors
•Batch requests: Group multiple operations into single requests when possible
•Cache responses: Store frequently accessed data to reduce API calls
•Upgrade your plan: Contact us if you consistently hit rate limits

Need Higher Limits?

If your application requires higher rate limits, we offer custom Enterprise plans with tailored limits to meet your needs.

Contact Sales

Changelog

Stay up to date with the latest changes, improvements, and fixes to the GECKO EDI API. We follow semantic versioning.

Latest

v1.2.0

minor

January 15, 2024

Added

•Support for EDI 867 (Product Transfer and Resale Report)
•New validation endpoint for batch document validation
•Webhook support for real-time document status updates

Changed

•Improved error messages with more detailed validation information
•Enhanced rate limiting with per-endpoint granular controls

Fixed

•Fixed issue with EDI 850 line item parsing
•Resolved timezone handling in document timestamps

v1.1.0

minor

December 1, 2023

Added

•Support for EDI 856 (Ship Notice/Manifest)
•Bulk document retrieval endpoint
•Filter documents by date range

Changed

•Updated authentication to support API key rotation
•Improved pagination performance for large document sets

v1.0.1

patch

November 15, 2023

Fixed

•Fixed validation error for optional fields in EDI 810
•Corrected rate limit header values
•Resolved issue with special characters in sender/receiver IDs

Security

•Enhanced API key encryption
•Implemented additional request validation

v1.0.0

major

November 1, 2023

Added

•Initial release of GECKO EDI API
•Support for EDI 850 (Purchase Order)
•Support for EDI 810 (Invoice)
•Document validation and status tracking
•RESTful API with JSON responses
•Comprehensive error handling

Version Guidelines

MAJOR: Breaking changes that may require updates to your integration
MINOR: New features and enhancements that are backward compatible
PATCH: Bug fixes and minor improvements