SAF API
Current Version: June 26, 2018
The Document contains SAF API developer guide and documentation for the main SAF API packages.
SAF API is written using Proto 3. Proto 3 is the latest version of the Protocol Buffers. It is a simple language-neutral and platform-neutral Interface Definition Language (IDL) for defining data structure schemas and programming interfaces. It supports both binary and text wire formats, and works with many different wire protocols on different platforms. Code written using Proto 3 is kept in file with the .proto extension.
The following UML Entity-Relationship Diagram (Fig.1) presents relationships between SAF entities described in the guides. UML notations used in the diagram are described here.
Fig.1. Entity-Relationship (ER) Diagram.
SAF defines two types of services: Actor and Manager services.
Actor Service - semi-automated application (some user tasks). Actor Service supports human machine interface and automate execution of an engagement processes on behalf of an actor.
An Actor suppose to use one Actor Service for all engagements. For example, ShipperSvc - an application , which automates engagements on behalf of a Shipper, ExporterSvc - a service , which automate engagements on behalf of a Exporter, etc
Manager Service - fully automated application (no user tasks) which tracks and controls execution of the engagement processes. One manager service controls engagements of a certain type. For instance, one ManagerCESvc controls engagements of type CE, ManagerCCSvc controls engagements of type CC, etc. It also allowed for one manager application to control multiple types of engagements,
Figure 1. contains list of engagements and services registered in SAF. The table also features relationship between engagement and services: a dot is an indication the the service participates in the engagement by exposing an interface, whch is utilized by other services in the engagement.
Fig.2. SAF Services.
SAF services are using Remote Procedure Call (RPC) Services . SAF defines the RPC service interfaces in a .proto file and the protocol buffer compiler will generate service interface code and stabs in a chosen programming language.
For example, the following .proto files defines a service interface ManagerCE with a method CreateEngagement that takes EEI message and returns saf.Empty message. The interface belongs to saf.ce.eu.v1a package. Please, note that - Proto 3 uses term service for definition of a service interface.
syntax = "proto3";
package saf.ce.usa.v1a;
import "saf/util/empty.proto";
option go_package = "github.com/gosaf/ce/usa/v1a";
service ManagerCE {
rpc CreateEngagement(EEI) returns (saf.util.Empty);
rpc GetTransport(Shipment) returns (saf.util.Empty);
rpc ReturnTransport(Transport) returns (saf.util.Empty);
}
A SAF service can expose multiple interfaces, however for an engagement each service exposes single interface.
Naming:
- The terms "Service Interface", "Interface" and SI are used interchangeably in the document.*
- Name Of the Service contains Name Of Actor and Engagement e.g. ManagerCE, ShipperCE, ShipperCC, etc
Package - group of service interfaces (SI) , required for a particular engagement. Since governing rules for engagements in different countries and regions of the world might not match, SAF defines one or more package for engagement. SAF package corresponds to package specifier defined in the Proto 3 Spec.
SAF package ID contains the following segments separated by dots:
- Prefix 'saf'
- Engagement Type
- Code for geographical area where the services shall be used e.g. us - USA, eu- European Union, gl- Global, etc.
- Version Number
For example, saf.ce.eu.v1a package.
TBD
Package Details
| Description | Customs Export Declaration Process in USA |
| Mode Of Transportation | Sea-freight, Containerized, Full Container Load (FCL) |
| Region | USA |
| Version | v1a |
| Engagement | CE |
| Actors | Exporter, Shipper, USA Customs |
| Start Event | Exporter filled EEI (Customs Export Declaration) for a shipment |
| End Event | Exporter and Shipper received confirmation that the shipment has been accepted by Customs |
| Data Object | ED - Export Declaration |
Sequence Diagram
Primary Path
| Step# | Description |
| 1 | Exporter enters EEI Shipment details into ExporterApp and ExporterApp sends request to ManagerCEApp to create CE engagement |
| 2 | ManagerCE sends SLOI - Shipper's Letter Of Instruction message to ShipperApp. |
| 3 | ShipperApp requests Carriage Rate from ManagerCCApp |
| 4 | ManagerCCApp returns Carriage Rate |
| 5 | ShipperApp requests Export Booking from ManagerCCApp |
| 5 | ShipperApp requests Export Booking from ManagerCCApp |
| 6 | ManagerCCApp sends Export Booking to ShipperApp |
| 7 | ShipperApp sends Transport Message to ManagerCCApp |
| 8 | ManagerCCApp sends EEI message to CustomsApp |
| 9 | CustomsApp sends EEI object to AES. Note: AES doesn't support SAF interface yet 👎, therefore CustomsApp communicates with AES using CBP Proprietary or ANSI X.12 performing as a 'facade' for AES. |
| 10 | AES accepts EEI and returns ITN number |
| 11 | CustomsAPP sends ITN message to ManagerCEApp. |
| 12 | ManagerCEApp sends ITN Message to ExporterApp. |
| 13 | ManagerCEApp sends ED Message to ShipperApp. |
| 14 | ShipperApp sends ED Message to ManagerCCApp. |
| Term | Definition |
| EEI | Electronic Export Information. Information required by AES to accept shipment. |
| Transport Data Object | Data Object containing transportation details such as Carrier Code, Vessel Name, Export Booking Number, etc |
| ITN | Internal Transaction Number. Confirmation number that proves a shipment has been accepted by AES. This number is unique for every shipment and must be provided to the U.S. Customs and Border Protection (CBP) at the port of export. |
Interfaces
ManagerCE
| Method | Client App | Server App | Parameter Message | Return Message |
| CreateCE | ExporterApp | ManagerCEApp | ||
| SetTransport | ShipperApp | ManagerCEApp | ||
| SetITN | CustomsApp | ManagerCEApp |
ExporterCE
| Method | Client App | Server App | Parameter Message | Return Message |
| SetITN | ManagerCEApp | ExporterApp |
CustomsCE
| Method | Client App | Server App | Parameter Message | Return Message |
| SetITN | SetEEI | CustomsApp | ||
| ReturnITN | AES | CustomsApp |
ShipperCE
| Method | Client App | Server App | Parameter Message | Return Message |
| SetSLOI | ManagerCEApp | ShipperApp | ||
| SetED | ManagerCEApp | ShipperApp |
Resources
- Google API Design Guide: https://cloud.google.com/apis/design/
- AESDirect User Guide (US CBP) https://www.census.gov/foreign-trade/aes/aesdirect/AESDirect-User-Guide.pdf
TBD
TBD
Package Details
| Description | Port-To-Port Transport (CC_PTP) |
| Mode Of Transportation | Sea-freight, Containerized, Full Container Load (FCL) |
| Region | All |
| Version | v1a |
| Engagement | CC |
| Actors | Exporter, Shipper, USA Customs |
| Start Event | Shipper requests quotation for carriage |
| End Event | Shipping Line delivers container to consignee at the port of discharge |
| Regulations | UCP 600:Article 20 |
| Documents | Ocean Transport Bill Of Lading |
| Typical Terms Of Carriage | Where the Carriage is Ocean Transport, the Shipping Line(Carrier) undertakes to perform and/or in his own name to procure performance of the Carriage from the Port of Loading to the Port of Discharge. If the Carrier is requested by the Merchant to procure Carriage by an inland carrier and the inland carrier in his discretion agrees to do so, such Carriage shall be procured by the Carrier as agent only to the Merchant. |
| Data Object | PTP |
Sequence Diagram
Actors & Responsibilities
As Per Bill Of Lading
| Actor | Responsibility |
| Shipping Line | Indicate terms and conditions of carriage or make reference to another source containing the terms and conditions of carriage |
| Shipping Line | Sign BOL and indicate that the goods have been shipped on board a named vessel at the port of loading |
| Master | Sign BOL |
Others
| Actor | Responsibility |
| Shipping Line | Carriage of Container |
| Shipping Line | Release Empty Container |
| Shipper | Pay Freight |
| Shipper | Provide Container VGM |
| Shipper | Forward Container to Port (Terminal) Of Loading |
| Consignee | Pickup from Port (Terminal) of Discharge |
| Consignee | Return empty container to the designated Depot |
Primary Path
| Step# | Description |
| 12 |
Glossary
| Term | Definition |
Interfaces
ManagerCE
| Method | Client App | Server App | Parameter Message | Return Message |
ExporterCE
| Method | Client App | Server App | Parameter Message | Return Message |
CustomsCE
| Method | Client App | Server App | Parameter Message | Return Message |
ShipperCE
| Method | Client App | Server App | Parameter Message | Return Message |
Resources