> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Atualizar rastreio de entrega > Defina ou atualize o rastreio de entrega em uma transação paga. Defina ou atualize as informações de rastreio de entrega em uma transação **paga**. Use na URL o UUID retornado como `id` da transação. Autentique com a API key da sua empresa (Bearer, API key ou Basic auth). Depois de definido, o rastreio aparece em [Consultar transação](/pt/api-reference/transactions/get) nos campos de entrega da transação. ## Campos da requisição O corpo é JSON com campos em snake\_case: | Campo | Tipo | Obrigatório | Restrições | | ------------------ | -------------- | ----------- | -------------------------------------------------------------------------------------- | | `tracking_code` | string | Sim | Sem espaços nas pontas, 1–255 caracteres, sem caracteres de controle ASCII. | | `delivery_status` | enum | Não | Um de `waiting`, `in_transit`, `delivered`. Padrão `in_transit` no primeiro envio. | | `tracking_url` | string \| null | Não | Sem espaços nas pontas, máx. 255 caracteres, deve começar com `http://` ou `https://`. | | `tracking_company` | string \| null | Não | Sem espaços nas pontas, 1–64 caracteres. | ### Omitir vs. null * **Omita** um campo opcional para manter o valor atual inalterado. * Envie **`null`** em `tracking_url` ou `tracking_company` para limpar um valor definido anteriormente. * Quando `delivery_status` é omitido, o status atual é preservado na atualização, ou assume `in_transit` na primeira vez que o rastreio é definido. * Uma entrega já marcada como `delivered` não pode voltar para `waiting` ou `in_transit` (retorna `409`). ## Idempotência e concorrência `PUT` é idempotente — repetir a mesma requisição produz o mesmo estado de entrega. Para concorrência otimista, envie o ETag da transação no header `If-Match`; um ETag desatualizado retorna `412 Precondition Failed`. ## Erros | Status | Significado | | ------ | --------------------------------------------------------------------- | | `400` | Requisição malformada. | | `401` | Credenciais ausentes ou inválidas. | | `404` | Transação não encontrada para esta empresa. | | `409` | Transição de status inválida (ex.: reverter uma entrega `delivered`). | | `412` | ETag do `If-Match` não confere. | | `422` | Validação falhou (restrições de campo não atendidas). | | `429` | Limite de requisições excedido. | ## Exemplo ```bash theme={null} curl -X PUT "https://api.pagou.ai/v2/transactions/{id}/delivery" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "tracking_code": "BR123456789BR", "delivery_status": "in_transit", "tracking_url": "https://tracking.carrier.com/BR123456789BR", "tracking_company": "Correios" }' ``` ```json theme={null} { "success": true, "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201", "data": { "status": "in_transit", "code": "BR123456789BR", "url": "https://tracking.carrier.com/BR123456789BR", "company": "Correios", "last_update": "2026-07-14T12:00:00.000Z" } } ``` O rastreio atualizado passa a aparecer em `GET /v2/transactions/{id}`. ## OpenAPI ````yaml api-reference/openapi-v2.json PUT /v2/transactions/{id}/delivery openapi: 3.1.0 info: title: Pagou API - v2 description: API for Pagou.ai Gateway version: 2.0.0 contact: name: Support url: https://pagou.ai email: support@pagou.ai servers: - url: https://api.pagou.ai description: Production server - url: https://api.sandbox.pagou.ai description: Sandbox server for testing security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] paths: /v2/transactions/{id}/delivery: put: tags: - Transactions summary: Update Delivery Tracking description: >- Set or update delivery tracking information on a paid transaction. Identify the transaction by the UUID returned as its public `id`. `tracking_code` is required; `delivery_status`, `tracking_url`, and `tracking_company` are optional. Omitting an optional field leaves its current value unchanged, while sending `null` for `tracking_url` or `tracking_company` clears it. When `delivery_status` is omitted, the existing status is preserved (or defaults to `in_transit` the first time delivery is set). A shipment already marked `delivered` cannot be moved back to `waiting` or `in_transit` (returns 409). Supports optimistic concurrency through `If-Match` with the transaction ETag (returns 412 on mismatch). operationId: putTransactionsByIdDelivery parameters: - schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true requestBody: required: true content: application/json: schema: type: object properties: tracking_code: type: string minLength: 1 maxLength: 255 description: Carrier tracking code for the shipment. Required. example: BR123456789BR delivery_status: description: >- Delivery status of the shipment. One of `waiting`, `in_transit`, or `delivered`. When omitted, the existing status is preserved on update, or defaults to `in_transit` on the first update. example: in_transit type: string enum: - waiting - in_transit - delivered tracking_url: description: >- Public URL where the buyer can track the shipment. Must start with `http://` or `https://`. Send `null` to clear a previously set value; omit to leave it unchanged. example: https://tracking.carrier.com/BR123456789BR nullable: true type: string maxLength: 255 tracking_company: description: >- Name of the carrier handling the shipment. Send `null` to clear a previously set value; omit to leave it unchanged. example: Correios nullable: true type: string minLength: 1 maxLength: 64 required: - tracking_code responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: type: object properties: status: nullable: true type: string enum: - waiting - in_transit - delivered code: nullable: true type: string url: nullable: true type: string company: nullable: true type: string last_update: nullable: true type: string format: date-time required: - status - code - url - company - last_update additionalProperties: false required: - success - requestId - data additionalProperties: false example: success: true requestId: 0190a2b4-18a7-7de0-9a43-69b7cf261201 data: status: waiting code: string url: string company: string last_update: '2026-07-14T12:00:00.000Z' '400': description: HTTP 400 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '401': description: HTTP 401 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '404': description: HTTP 404 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '409': description: HTTP 409 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '412': description: HTTP 412 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '422': description: HTTP 422 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '429': description: HTTP 429 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} default: description: RFC 7807 Problem Details error response content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] components: schemas: ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string code: type: string additionalProperties: true additionalProperties: true ProblemDetails: type: object description: RFC 7807 Problem Details object. properties: type: type: string format: uri-reference title: type: string status: type: number detail: type: string instance: type: string format: uri-reference required: - type - title - status - detail additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: apiKey BasicAuth: type: http scheme: basic description: Use Basic auth with username `token` and password `x`. ````