{
  "openapi": "3.1.0",
  "info": {
    "title": "Golden Arcus OMS API",
    "version": "1.0.0",
    "description": "Shipment status with timestamps, events and signed webhooks for your own system."
  },
  "servers": [
    {
      "url": "https://api.ga-oms.com"
    }
  ],
  "paths": {
    "/v1/shipments": {
      "get": {
        "operationId": "v1_shipments",
        "summary": "List shipments",
        "description": "The account's own shipments, newest first, a page at a time. Filters: one MAWB, a phase, changed since a moment.",
        "x-scope": "shipments:read",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many to return, up to 100",
            "schema": {
              "default": 25,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "The id of the last shipment of the page before",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "mawb",
            "in": "query",
            "required": false,
            "description": "NNN-NNNNNNNN",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "phase",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "prealert",
                "flight",
                "customs",
                "released",
                "warehouse",
                "shipped"
              ]
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "description": "ISO 8601: shipments changed at or after it",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentList"
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (invalid_request)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "No valid key (invalid_key, wrong_environment, account_closed)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope (missing_scope)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many calls (rate_limited: 120 a minute per key; too_many_wrong_keys: 20 a minute per address)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipments/{id}": {
      "get": {
        "operationId": "v1_shipment",
        "summary": "Retrieve a shipment",
        "description": "One of the account's own shipments, by its id.",
        "x-scope": "shipments:read",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (invalid_request)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "No valid key (invalid_key, wrong_environment, account_closed)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope (missing_scope)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not found (not_found)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many calls (rate_limited: 120 a minute per key; too_many_wrong_keys: 20 a minute per address)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "operationId": "v1_events",
        "summary": "List events",
        "description": "The events about the account's shipments, oldest first: what a webhook is sent, to fetch instead or to catch up.",
        "x-scope": "shipments:read",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many to return, up to 100",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "The id of the last event you have: the ones after it",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (invalid_request)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "No valid key (invalid_key, wrong_environment, account_closed)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope (missing_scope)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many calls (rate_limited: 120 a minute per key; too_many_wrong_keys: 20 a minute per address)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "shipment.created": {
      "post": {
        "operationId": "on_shipment_created",
        "summary": "A shipment is on file for the account",
        "description": "Signed as Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). The whole shipment is sent each time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Received. Any other answer, or none in 10 seconds, is retried."
          }
        }
      }
    },
    "shipment.updated": {
      "post": {
        "operationId": "on_shipment_updated",
        "summary": "Something the account can see on a shipment changed",
        "description": "Signed as Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). The whole shipment is sent each time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Received. Any other answer, or none in 10 seconds, is retried."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "ga_live_… in production, ga_test_… on the test server"
      }
    },
    "schemas": {
      "Shipment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^shp_[0-9a-f]{32}$",
            "description": "Stays the same when the MAWB number is corrected"
          },
          "object": {
            "type": "string",
            "const": "shipment"
          },
          "mawb": {
            "type": "string",
            "description": "NNN-NNNNNNNN"
          },
          "part": {
            "description": "The letter of a split MAWB part shown on its own; null otherwise",
            "type": [
              "string",
              "null"
            ]
          },
          "service_type": {
            "type": "string",
            "description": "T01, T11 or Ground Handling"
          },
          "origin": {
            "description": "Departure airport",
            "type": [
              "string",
              "null"
            ]
          },
          "destination": {
            "type": "string",
            "description": "LAX, ORD, JFK or IAH"
          },
          "flight": {
            "type": [
              "string",
              "null"
            ]
          },
          "cartons": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Cartons on the MAWB"
          },
          "eta": {
            "anyOf": [
              {
                "type": "string",
                "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
              },
              {
                "type": "null"
              }
            ]
          },
          "ata": {
            "anyOf": [
              {
                "type": "string",
                "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
              },
              {
                "type": "null"
              }
            ]
          },
          "phase": {
            "type": "string",
            "enum": [
              "prealert",
              "flight",
              "customs",
              "released",
              "warehouse",
              "shipped"
            ]
          },
          "customs": {
            "type": "string",
            "enum": [
              "not_arrived",
              "pending",
              "released",
              "hold"
            ]
          },
          "hold": {
            "type": "boolean",
            "description": "True while a hold is on the shipment; never once it has shipped in full"
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "hold",
                "pga",
                "action_required"
              ]
            },
            "description": "More values may be added: ignore one you do not know"
          },
          "status_text": {
            "type": "string",
            "description": "The status as our operations team wrote it. For display, not for logic"
          },
          "checkpoints": {
            "type": "object",
            "properties": {
              "prealert": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "booked": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "arrived": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "released": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "in_warehouse": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "breakdown": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              },
              "shipped": {
                "type": "object",
                "properties": {
                  "reached": {
                    "type": "boolean"
                  },
                  "time": {
                    "anyOf": [
                      {
                        "type": "string",
                        "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "reached",
                  "time"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "prealert",
              "booked",
              "arrived",
              "released",
              "in_warehouse",
              "breakdown",
              "shipped"
            ],
            "additionalProperties": false
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "channel": {
                  "type": "string",
                  "description": "Last-mile channel"
                },
                "cartons": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string"
                },
                "customer_ref": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "received_at": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Into our warehouse"
                },
                "shipped_at": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Out of our warehouse"
                }
              },
              "required": [
                "channel",
                "cartons",
                "status",
                "customer_ref",
                "received_at",
                "shipped_at"
              ],
              "additionalProperties": false
            }
          },
          "parts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "part": {
                  "description": "The part's letter; null for the first flight",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "cartons": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "eta": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ata": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "lines": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "received": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "shipped": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                }
              },
              "required": [
                "part",
                "cartons",
                "eta",
                "ata",
                "lines",
                "received",
                "shipped"
              ],
              "additionalProperties": false
            },
            "description": "Empty unless the MAWB arrives on more than one flight; then one entry per flight"
          },
          "cancelled": {
            "type": "boolean"
          },
          "updated_at": {
            "type": "string",
            "description": "ISO 8601 with offset, in the destination airport's local time; a date (YYYY-MM-DD) when no time is on file"
          }
        },
        "required": [
          "id",
          "object",
          "mawb",
          "part",
          "service_type",
          "origin",
          "destination",
          "flight",
          "cartons",
          "eta",
          "ata",
          "phase",
          "customs",
          "hold",
          "flags",
          "status_text",
          "checkpoints",
          "lines",
          "parts",
          "cancelled",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "ShipmentList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            }
          },
          "has_more": {
            "type": "boolean",
            "description": "More after these: ask again with `after` set to the last id"
          }
        },
        "required": [
          "object",
          "data",
          "has_more"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9A-Za-z-]+$",
            "description": "The same id on every retry: ignore one you already have"
          },
          "object": {
            "type": "string",
            "const": "event"
          },
          "type": {
            "type": "string",
            "enum": [
              "shipment.created",
              "shipment.updated"
            ],
            "description": "More types may be added: ignore one you do not know"
          },
          "created_at": {
            "type": "string",
            "description": "ISO 8601, UTC"
          },
          "changed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The shipment fields that differ from the event before, e.g. \"phase\", \"checkpoints.arrived\", \"lines\""
          },
          "data": {
            "type": "object",
            "properties": {
              "object": {
                "$ref": "#/components/schemas/Shipment"
              }
            },
            "required": [
              "object"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "object",
          "type",
          "created_at",
          "changed",
          "data"
        ],
        "additionalProperties": false
      },
      "EventList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "has_more": {
            "type": "boolean",
            "description": "More after these: ask again with `after` set to the last id"
          }
        },
        "required": [
          "object",
          "data",
          "has_more"
        ]
      },
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The page that explains the code"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "code": {
            "type": "string",
            "description": "Stable: decide on this, never on the words"
          },
          "detail": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "description": "Quote it when asking us about a call"
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "code",
          "detail",
          "request_id"
        ],
        "additionalProperties": false
      }
    }
  }
}
