# Create Guide

Creates a new shipping, transport or devolution.

Endpoint: POST /{guides-type}.json
Version: 2.0.0
Security: apiKeyAuth

## Query parameters:

  - `api_key` (string, required)
    Your API Key.
    Example: "YOUR_API_KEY"

## Path parameters:

  - `guides-type` (string, required)
    The type of the guide document.
    Enum: "shippings", "transports", "devolutions"

## Request fields (application/json):

  - `shipping` (object, required)
    address_from and address_to (each with detail, city, postal_code and country) are required only on Portuguese accounts; otherwise the request fails with 422 No address_from element provided / No address_to element provided.

  - `shipping.date` (string, required)
    dd/mm/yyyy
    Example: "03/12/2017"

  - `shipping.due_date` (string)
    dd/mm/yyyy. Defaults to date when omitted.
    Example: "03/12/2017"

  - `shipping.loaded_at` (string, required)
    dd/mm/yyyy HH:mm:ss. Must not be in the past, otherwise the request fails with 422 Load date must be on or after .
    Example: "02/12/2030 19:00:00"

  - `shipping.license_plate` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "11-AA-22"

  - `shipping.address_from` (object)

  - `shipping.address_from.detail` (string, required)
    255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
    Example: "Rua 5"

  - `shipping.address_from.city` (string, required)
    255-character limit is the database column default on the Address model, not an explicit business rule.
    Example: "Lisboa"

  - `shipping.address_from.postal_code` (string, required)
    255-character limit is the database column default on the Address model, not an explicit business rule.
    Example: "1000-555"

  - `shipping.address_from.country` (string, required)
    Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
    Example: "Portugal"

  - `shipping.address_to` (object)

  - `shipping.reference` (string)
    Example: "999"

  - `shipping.observations` (string)
    No enforced character limit (text column).
    Example: "Observations"

  - `shipping.retention` (string)
    Example: "0"

  - `shipping.tax_exemption` (string)
    Example: "M01"

  - `shipping.sequence_id` (string)
    Example: "12345"

  - `shipping.manual_sequence_number` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "1"

  - `shipping.client` (object)
    To identify an existing client, send id, code, or name — not all three are required. Resolution priority: if id is sent and matches a client on the account, that client is used and name/code are ignored. Without id, if code matches an existing client, that client is used and name is not needed. Without an id/code match, name is used to find or create the client. Creating a brand-new client (no id/code match) still requires name; code is always optional and is never generated automatically by InvoiceXpress.

  - `shipping.client.id` (integer)
    Internal client ID. Preferred way to identify an existing client — see the object description.
    Example: 1310176

  - `shipping.client.name` (string)
    Example: "Client Name"

  - `shipping.client.code` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "A1"

  - `shipping.client.email` (string)
    Example: "foo@bar.com"

  - `shipping.client.address` (string)
    No enforced character limit (text column).
    Example: "Saldanha"

  - `shipping.client.city` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "Lisbon"

  - `shipping.client.postal_code` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "1050-555"

  - `shipping.client.country` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "Portugal"

  - `shipping.client.fiscal_id` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "508000000"

  - `shipping.client.website` (string)
    Example: "www.website.com"

  - `shipping.client.phone` (string)
    Example: "910000000"

  - `shipping.client.fax` (string)
    Example: "210000000"

  - `shipping.items` (array, required)

  - `shipping.items.name` (string, required)
    Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters.
    Example: "Item Name"

  - `shipping.items.description` (string)
    Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters.
    Example: "Item Description"

  - `shipping.items.unit_price` (number, required)
    Example: 100

  - `shipping.items.quantity` (number, required)
    Example: 5

  - `shipping.items.unit` (string)
    Restricted to a fixed set of unit values rather than length-limited free text.
    Example: "service"

  - `shipping.items.discount` (number)
    Example: 50

  - `shipping.items.tax` (object)

  - `shipping.tax_exemption_reason` (string)
    Validated at 210 characters by the document model, below the 255-character database column limit.
    Example: "M00"

  - `shipping.load_site` (string)
    No enforced character limit (text column).
    Example: "Lisbon, Portugal"

  - `shipping.delivery_site` (string)
    No enforced character limit (text column).
    Example: "Madrid, Spain"

## Response 201 fields (application/json):

  - `shipping` (object)
    Wrapper key matches the singular of the requested guide type — shipping, transport or devolution. Shown here as "shipping".

  - `shipping.id` (integer)
    Example: 541797

  - `shipping.status` (string)
    Example: "final"

  - `shipping.archived` (boolean)

  - `shipping.type` (string)
    Example: "Shipping"

  - `shipping.sequence_number` (string)
    Example: "1/D"

  - `shipping.inverted_sequence_number` (string)
    Example: "D/1"

  - `shipping.atcud` (string)
    Example: "ABCD1234-1"

  - `shipping.date` (string)
    Example: "13/07/2017"

  - `shipping.due_date` (string)
    dd/mm/yyyy
    Example: "27/07/2026"

  - `shipping.reference` (string,null)

  - `shipping.observations` (string,null)
    No enforced character limit (text column).

  - `shipping.retention` (string,null)

  - `shipping.loaded_at` (string)
    dd/mm/yyyy HH:mm:ss. Note the list endpoint returns this same field as date-only (dd/mm/yyyy).
    Example: "27/07/2026 23:00:00"

  - `shipping.license_plate` (string,null)
    255-character limit is the database column default, not an explicit business rule.
    Example: "11-AA-22"

  - `shipping.permalink` (string)
    Example: "https://web.invoicexpress.com/documents/541797d75bbee48911934cbd4a4294946a324295f52b08"

  - `shipping.saft_hash` (string)
    No enforced character limit (text column).
    Example: "vaDf"

  - `shipping.sum` (number)
    Example: 1

  - `shipping.discount` (number)

  - `shipping.before_taxes` (number)
    Example: 1

  - `shipping.taxes` (number)
    Example: 0.07

  - `shipping.total` (number)
    Example: 1.07

  - `shipping.currency` (string)
    Example: "Euro"

  - `shipping.address_from` (object)

  - `shipping.address_from.country` (string)
    Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
    Example: "Portugal"

  - `shipping.address_from.postal_code` (string)
    255-character limit is the database column default on the Address model, not an explicit business rule.
    Example: "1050-083"

  - `shipping.address_from.detail` (string)
    255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
    Example: "Avenida Duque D'Avila, 46 - 3ºA"

  - `shipping.address_from.city` (string)
    255-character limit is the database column default on the Address model, not an explicit business rule.
    Example: "Lisboa"

  - `shipping.address_to` (object)

  - `shipping.client` (object)

  - `shipping.client.name` (string)
    Example: "John"

  - `shipping.client.country` (string)
    255-character limit is the database column default, not an explicit business rule.
    Example: "Portugal"

  - `shipping.items` (array)

  - `shipping.items.name` (string)
    Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters.
    Example: "iPhone"

  - `shipping.items.description` (string,null)
    Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters.

  - `shipping.items.unit_price` (string)
    Example: "1.0"

  - `shipping.items.unit` (string,null)
    Restricted to a fixed set of unit values rather than length-limited free text.
    Example: "service"

  - `shipping.items.quantity` (string)
    Example: "1.0"

  - `shipping.items.tax` (object)

  - `shipping.items.tax.value` (number)
    Example: 7

  - `shipping.items.subtotal` (number)
    Example: 1

  - `shipping.items.tax_amount` (number)
    Example: 0.07

  - `shipping.items.discount_amount` (number)

  - `shipping.sequence_id` (integer,null)
    Example: 12345

  - `shipping.tax_exemption` (string)
    Example: "M01"

  - `shipping.at_doc_code_id` (string,null)
    Read-only. Written only by the AT gateway and never accepted on input. The 255-character limit is the database column default, not an explicit business rule.
    Example: "999"

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.error` (string)
    Example: "Authentication Error"

## Response 422 fields (application/json):

  - `errors` (array)
    Example: [{"error":"Date can't be blank"},{"error":"This document is being saved by another request. Please try again."}]

  - `errors.error` (string)