Test and production

• Test and production are separate, each with its own connection details: API base URL and key, SFTP host, AS2 ID and URL, cXML endpoint.
• Build and test against the test environment. Switch to the production details when you go live.
• Before you start the test cases, check that your test connection works both ways: you can receive from us and send to us.
• If your firewall needs an allow-list, our IP address comes with your connection details.
• Every JSON and CSV document carries our company ID; JSON orders and invoices also carry yours. Both IDs, and the vendor number for CSV files, come with your connection details. The samples use 111111 for ZAGENO, 222222 for you and 1234567 as the vendor number.

API cXML and JSON

• JSON calls authenticate with an API key that comes with your connection setup. Set up your test key first.
• Generating a new key replaces the old one and breaks anything still using it, so check with your team before you generate one.
• cXML documents carry a shared secret in the Sender credential, as in the samples.
• For cXML, send us your shared secret, your cXML ID and your test and production endpoints, so we can post orders to you.
• The full API reference for test and production comes with your connection setup.

SFTP

• You log in with a username and password. No certificates or keys are needed.
• Create a dedicated login for automated transfers, registered to a shared mailbox your team can reach, so a password change or someone leaving doesn't break your integration.
• Before you automate, log in once with a standard SFTP client such as FileZilla or WinSCP to check your login and your folders.
• Your site has one folder per format. Use only the folder for your format.
• Inbound holds files from us, such as purchase orders. Put your acknowledgements, ship notices and invoices in Outbound. Archive is optional, for files you have processed; nothing in it is picked up.
• Each JSON or cXML order arrives as its own file. After you collect it, delete it or move it to Archive: removing the file tells us you received the order, and new orders aren't delivered while old order files stay in Inbound.
• Your exact folder layout comes with your connection details.

AS2 EDI

• AS2 uses SHA-2. Send every message signed and encrypted (S/MIME). The encryption algorithm comes with your connection details.
• Request a synchronous MDN (receipt) for every message.
• You get separate AS2 IDs and URLs for test and production. One certificate covers both.
• We send you our AS2 ID, AS2 URL and public certificate at setup. You send us yours.
• If you allow-list, the IP address in your connection details is the one we send from. It isn't our AS2 receiving address.

cXML API or SFTP

Sample files

• Purchase orderOrderRequest
• Purchase order against your quoteOrderRequest
• Purchase order with customer-specific pricingOrderRequest
• PO acknowledgementConfirmationRequest
• Updated PO acknowledgementConfirmationRequest
• Ship noticeShipNoticeRequest
• InvoiceInvoiceDetailRequest

EDI AS2 or SFTP

Specifications

• 850 Purchase orderPDF
• 855 PO acknowledgementPDF
• 856 Ship noticePDF
• 810 InvoicePDF

EDI basics

• ZAGENO's EDI documents follow ANSI X12 version 4010.
• We send 850 purchase orders over the connection you chose. You send 855, 856 and 810 back over the same connection.
• Send a 997 functional acknowledgement for each EDI document you receive.
• Use the sender and receiver IDs from your connection setup. A document whose IDs don't match is rejected.

JSON API or SFTP

Sample files

• Purchase orderJSON
• PO acknowledgementJSON
• Ship noticeJSON
• InvoiceJSON

CSV SFTP or Supplier Portal

Templates

• Acknowledgement templateCSV
• Ship notice templateCSV
• Invoice templateCSV

Acknowledgements

• Every acknowledgement that accepts or backorders units carries an estimated ship date.
• For each order line, state the units you accept, backorder and cancel. Together they equal the quantity ordered.
• Use our PO number and the line numbers from our purchase order.
• Acknowledge each order line once. After that, send only updates.
• When you cancel a line, give the reason if your format has a field for it.
• Send an updated acknowledgement as soon as an estimated ship date or a line's status changes. Give the estimated ship date for units you accept or backorder, as in a first acknowledgement, and add your format's update flag, so we don't read it as a new partial acknowledgement.

Update flag by format

A first acknowledgement uses operation="new" in cXML (the default) and BAK01 = 00 in an EDI 855. JSON and CSV need no flag. JSON orders may carry an attribute named Acknowledgement Update?. Ignore it. The update flag goes on your acknowledgement, not on the order.

Ship notices

• Every order that isn't cancelled needs a ship notice. Send one each time you ship.
• Ship only the items and lines on our purchase order, with its PO number and line numbers. A ship notice whose items don't match the order doesn't update the order.
• Give the carrier and tracking number. We pass them on, so the customer knows the order has shipped.
• Give the expected delivery date and the ship-from address, and the ship date where your format has a field for it.
• Carrier codes: use the carrier's SCAC (for example FDE for FedEx Express, FDEG for FedEx Ground, UPSN for UPS), or your own code once we have mapped it at setup.

Where the carrier code goes

No tracking number

• Items have shipped but you have no tracking number? Still send the ship notice: we can only update the customer and accept your invoice once the shipment is recorded.
• Set the carrier code to UNSP and the tracking number to exactly NO TRACKING PROVIDED.
• Still send every other detail: ship-from address, expected delivery date, items and quantities, and the ship date where your format has a field for it.

By format

Invoices

• We process invoices only once your payment terms are set up.
• Invoice only what you have shipped, and send the ship notice first. You can't invoice more units of a line than your ship notices report.
• Each line's unit price must match our purchase order line exactly. One mismatch fails the whole invoice.
• US orders: sales tax depends on the ship-to state. See our resale certificates page. If an invoice fails on tax, the error names the state. Send a new invoice with the tax corrected.
• Give each invoice its own invoice number, an invoice date and our PO number. If no currency is given, USD is assumed.
• Add a remit-to address only if your account has no default one. Invoices carry payment terms; credit memos don't need them.