> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Enviar documento
> Envia uma prova de contestação — nota fiscal, comprovante de entrega, contrato — enquanto a janela de defesa está aberta.
`POST /chargebacks/:id/documents`
Faz parte do recurso [Chargebacks](/pt-BR/chargebacks) — as etapas do caso e a janela de defesa
estão lá.
Anexa uma prova ao caso. São obrigatórios o **tipo** e o **arquivo**; a descrição é opcional.
**A janela fecha, e depois disso não há recurso.** O envio só é aceito enquanto o caso está em
`under_review` **e** o `deadlineAt` não passou — fora disso a resposta é `409`. Quem define esse
prazo é a adquirente, não você: confira o `deadlineAt` do caso antes de montar a defesa.
**O arquivo vai em base64, no corpo JSON.** Não é `multipart/form-data`. O campo `file` aceita o
base64 puro ou com o prefixo data URI (`data:application/pdf;base64,…`) — os dois funcionam.
**O tipo do arquivo é detectado pelo conteúdo, não pelo nome.** A validação lê a assinatura
binária dos primeiros bytes, então renomear um arquivo para `.pdf` não o faz passar. São aceitos
**PDF, JPEG, PNG e WebP**, com até **10 MB** já decodificados. Qualquer outra coisa responde `400`.
**`type` classifica a prova**, e ajuda quem for analisar o caso: `invoice` (nota fiscal),
`delivery_proof` (comprovante de entrega), `signed_contract` (contrato assinado), `screenshot`
(captura de tela) e `other`. Use `description` para o que o tipo não diz — o número da nota, a data
da conversa, o que for.
Endpoint idempotente. Envie o header `Idempotency-Key` para que um retry por timeout não anexe o
mesmo documento duas vezes. Veja [Convenções](/pt-BR/convencoes).
**A resposta não devolve o arquivo nem um link para ele.** Ela confirma o registro — `id`, `type`,
`contentType`, `size` e as datas. Para baixar depois, use
[`GET /chargebacks/:id/documents/:documentId/download`](/pt-BR/chargebacks/documents-download).
## OpenAPI
````yaml openapi/psp.json POST /chargebacks/{id}/documents
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/chargebacks/{id}/documents:
post:
tags:
- Chargebacks
summary: Upload de documento
description: Envia documento de contestação para o chargeback.
operationId: ChargebackController_uploadDocument
parameters:
- name: id
in: path
required: true
description: ID do chargeback
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- invoice
- delivery_proof
- signed_contract
- screenshot
- other
description: >-
Tipo do documento de contestação: invoice (nota/fatura),
delivery_proof (comprovante de entrega), signed_contract
(contrato assinado), screenshot (captura de tela) ou other
(outro).
description:
type: string
maxLength: 500
nullable: true
description: Descrição ou observação sobre o documento.
file:
type: string
minLength: 1
description: Conteúdo do arquivo do documento (base64).
required:
- type
- file
responses:
'201':
description: Documento enviado
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
chargebackId:
type: string
description: ID do chargeback ao qual o registro pertence.
type:
type: string
description: >-
Tipo do documento de contestação: `invoice`,
`delivery_proof`, `signed_contract`, `screenshot` ou
`other`.
contentType:
type: string
description: 'Tipo MIME do arquivo enviado (ex.: application/pdf).'
size:
type: integer
description: Tamanho do arquivo enviado, em bytes.
description:
type: string
nullable: true
description: Descrição do registro.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: cbkd_y4bf4q9kn7nfbksmvfjiwc5ba
chargebackId: cbk_v5wylkgvv2rls5tihmuybrz9v
type: delivery_proof
contentType: application/pdf
size: 512340
description: Comprovante de entrega assinado pelo cliente
createdAt: '2025-06-30T11:25:00.000Z'
updatedAt: '2025-06-30T11:25:00.000Z'
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Chargeback não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Document not found
'409':
description: Upload não permitido no status atual
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: CONFLICT
message: No refundable payment found
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````