# Guides Create shippings, transports & devolutions and send them to your clients. ## Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/invoices/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ## Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/guides/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ## List Guides - [GET /api/v3/guides](https://docs.invoicexpress.com/v3/guides/listv3guides.md): Returns a list of all your guides. ## List Guides (POST) - [POST /api/v3/guides](https://docs.invoicexpress.com/v3/guides/listv3guidespost.md): Same as GET /api/v3/guides, with the filters and pagination options sent in a JSON body instead of the query string. Useful when the filters (for example long id or client_id lists) do not fit in a URL. Returns the same response. ## Get Guides Summary - [POST /api/v3/guides/summary](https://docs.invoicexpress.com/v3/guides/getv3guidessummary.md): Returns the totals of the specific documents select ## Create Guide - [POST /api/v3/{guides-type}](https://docs.invoicexpress.com/v3/guides/createv3guide.md): Creates a new guide of the specified type, as a draft. The request body wrapper key must match the path segment: - shipping for shippings - transport for transports - devolution for devolutions loaded_at and at least one item are required. Portuguese accounts must also send address_from and address_to, each with detail, city, postal_code and country. ## Get New Guide Defaults - [GET /api/v3/{guides-type}/new](https://docs.invoicexpress.com/v3/guides/getv3newguide.md): Returns the defaults and choices used to fill in a new guide of the specified type (sequences, currencies, taxes, exemption reasons, due date and retention choices, address countries). Nothing is created. ## Calculate Guide Summary - [POST /api/v3/{guides-type}/calculate_summary](https://docs.invoicexpress.com/v3/guides/calculatev3guidesummary.md): Calculates the financial summary of a guide from its items, retention, global discount, currency and tax exemption, without saving anything. Unlike update_summary, the input is not validated — invalid values are coerced and a missing wrapper gives an all-zero summary — so it always answers 200 unless an unexpected error occurs. ## Update Guide Summary - [POST /api/v3/{guides-type}/update_summary](https://docs.invoicexpress.com/v3/guides/updatev3guidesummary.md): Calculates and returns the financial summary (totals, taxes, discounts, retention) for an guide based on the provided guide data without saving the guide. This endpoint is useful for previewing calculations before creating or updating an guide. ## Get Guide by ID - [GET /api/v3/{guides-type}/{id}](https://docs.invoicexpress.com/v3/guides/getv3guidebyid.md): Retrieves detailed information about a specific document including client data, items, financial summary, and account information ## Update Guide - [PUT /api/v3/{guides-type}/{id}](https://docs.invoicexpress.com/v3/guides/updatev3guide.md): Updates a guide of the specified type. The wrapper key must match the path segment (shipping, transport or devolution). The same rules as on create apply: loaded_at (not in the past) and at least one item are required, and Portuguese accounts must send complete address_from and address_to. The item list replaces the existing items. Guides that are sent, settled, deleted, canceled or second copies can no longer be edited. ## Clone Guide - [GET /api/v3/{guides-type}/{id}/clone](https://docs.invoicexpress.com/v3/guides/clonev3guide.md): Returns a new, unsaved draft guide of the specified type pre-filled from an existing document — nothing is created. The clone gets today's date, loaded_at 5 minutes from now, the account's default sequence for the type and, for Portuguese accounts, copies of the source addresses. Submit it with POST /api/v3/{guides-type} to create it. Unsaved fields such as id are null. ## List guide movements - [GET /api/v3/{guides-type}/{id}/movements](https://docs.invoicexpress.com/v3/guides/listv3guidemovements.md): Returns the payment and reimbursement movements of the specified guide and its related documents. Usually empty for guides. ## Archive a guide document - [PUT /api/v3/{guides-type}/{id}/archive](https://docs.invoicexpress.com/v3/guides/archivev3guidedocument.md): Archives the specified guide document by setting its archived flag to true and returns the updated document. ## Archive a guide document - [PATCH /api/v3/{guides-type}/{id}/archive](https://docs.invoicexpress.com/v3/guides/archivev3guidedocumentpatch.md): Archives the specified guide document by setting its archived flag to true and returns the updated document. ## Creates a comment for a document - [POST /api/v3/{guides-type}/{id}/comments](https://docs.invoicexpress.com/v3/guides/createv3guidedocumentcomment.md): Creates a new comment for the specified document. Comments can only be deleted within 15 minutes of creation. ## Deletes a comment from a document - [DELETE /api/v3/{guides-type}/{id}/comments/{comment_id}](https://docs.invoicexpress.com/v3/guides/deletev3guidedocumentcomment.md): Deletes a comment from the specified document. Comments can only be deleted within 15 minutes of creation and only by the author. ## Change document state - [PUT /api/v3/{guides-type}/{id}/change-state.json](https://docs.invoicexpress.com/v3/guides/changev3guidedocumentstate.md): Changes the state of a guide-type document (guides-type path segment: shippings, transports, or devolutions). | From | To | Value in request body | | :--- | :--- | :--- | | draft | final | finalized | | draft | deleted | deleted | | final | canceled | canceled | To cancel, send the reason in message inside the wrapper, e.g. {"transport": {"state": "canceled", "message": "Goods were not shipped"}}. Without it the API returns 422 "The cancellation reason is a required field". ## Download guide PDF - [GET /api/v3/{guides-type}/{id}/pdf](https://docs.invoicexpress.com/v3/guides/getv3guidepdf.md): Returns the PDF URL for the specified guide or indicates if PDF generation is in progress. ## Get QR Code - [GET /api/v3/{guides-type}/{id}/qr_code](https://docs.invoicexpress.com/v3/guides/getv3guideqrcode.md): Returns the QR Code URL for the specified document. ## Get send document configuration - [GET /api/v3/{guides-type}/{id}/send](https://docs.invoicexpress.com/v3/guides/getv3guidesendconfig.md): Returns the pre-filled email data for sending a guide document to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context. ## Send document by email - [POST /api/v3/{guides-type}/{id}/send](https://docs.invoicexpress.com/v3/guides/sendv3guidedocument.md): Sends the specified guide document by email to the client. ## List related documents - [GET /api/v3/{guides-type}/{id}/related_documents](https://docs.invoicexpress.com/v3/guides/listv3guiderelateddocuments.md): Returns the list of documents related to the specified guide document. ## Returns timeline activities for a specific document - [GET /api/v3/{guides-type}/{id}/timeline](https://docs.invoicexpress.com/v3/guides/getv3guidetimeline.md): Retrieves timeline activities for a specific document including status changes, comments, and other events ## Unarchive a guide document - [PUT /api/v3/{guides-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/guides/unarchivev3guidedocument.md): Unarchives the specified guide document by setting its archived flag to false and returns the updated document. ## Unarchive a guide document - [PATCH /api/v3/{guides-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/guides/unarchivev3guidedocumentpatch.md): Unarchives the specified guide document by setting its archived flag to false and returns the updated document. ## Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/estimates/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice.