> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Adicionar imagens a uma sessão, API Didit
> Na Didit, anexe uma imagem ou PDF extra ao resultado de verificação de identidade ou comprovativo de morada de uma sessão KYC concluída.
Prompt da API para adicionar imagens a uma sessão
Copiar o prompt para a área de transferência
\`Attach an extra image or PDF to a finished Didit User Verification (KYC) session through the API.
Endpoint:
PATCH [https://verification.didit.me/v3/session/\{session\_id}/add-images/](https://verification.didit.me/v3/session/\{session_id}/add-images/)
Authentication:
Send my Didit API key in the x-api-key header. A scoped key needs sessions: write.
Goal:
* Add evidence collected outside the verification flow (for example the back of an ID document, or a supporting letter) to the session's ID verification or Proof of Address result, so reviewers see it with the rest of the session.
Request (multipart/form-data):
* file (required): JPG, JPEG, PNG, WEBP, TIFF or PDF, at most 15 MB as uploaded. Didit compresses it and rejects it if it is still over 2 MB (2,097,152 bytes) after compression.
* model\_type (required): "kyc" for the ID verification, "poa" for the Proof of Address.
* file\_password (optional): the password of an encrypted PDF.
Behavior:
* The session must be Approved, Declined, In Review or Kyc Expired, and must have the result named by model\_type. Business (KYB) sessions are not supported.
* When the step ran more than once, the file goes to the most recent result.
* Each call adds one file and keeps the existing ones.
* The file then appears in extra\_files of id\_verifications\[] or poa\_verifications\[] in GET /v3/session/{session_id}/decision/.
* A FILE\_ADDED entry is added to the session's activity log. No webhook is sent and the session status does not change.
* Rate limit: 10 requests per minute per API key.
Example call:
curl -X PATCH "[https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/](https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/)" \
-H "x-api-key: YOUR\_API\_KEY" \
-F "file=@back-of-id.jpg" \
-F "model\_type=kyc"
What to read from the response:
* extra\_files: short-lived presigned links to every extra file of that result, including the new one. A scoped key without media: read receives them as null.
Failure modes:
* 400: file or model\_type missing, unsupported format, file too large before or after compression, encrypted PDF without the right file\_password.
* 401: the API key has expired.
* 403: missing key (a wrong, revoked or expired key gets 401), a key of another application, a scoped key without sessions: write, or a request from outside the key's IP allowlist.
* 404: the session does not exist, was deleted, is outside a scoped key's limits, is not in a reviewable status, or has no result of that model\_type.
* 429: more than 10 calls in a minute. Wait for Retry-After seconds.
Side effects: stores the file with the session and adds an activity entry.
For the full integration shape, see /integration/integration-prompt.\`
Colar em
As ligações pré-assinadas em `extra_files` expiram. Obtenha novas a partir da [decisão da sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md) quando precisar dos ficheiros mais tarde. Para corrigir os dados extraídos de um documento, use [Atualizar dados da sessão](https://docs.didit.me/pt/sessions-api/update-data.md).
## OpenAPI
````yaml pt/openapi-25.json PATCH /v3/session/{sessionId}/add-images/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/{sessionId}/add-images/:
patch:
tags:
- Sessions
summary: Adicionar uma imagem a uma sessão
description: >-
Anexe uma imagem ou PDF adicional ao resultado da Verificação de
identidade (`model_type=kyc`) ou Comprovativo de morada
(`model_type=poa`) de uma sessão de Verificação de utilizadores (KYC)
concluída, por exemplo, provas recolhidas fora do fluxo. A sessão deve
estar como `Approved`, `Declined`, `In Review` ou `Kyc Expired` e
incluir o resultado indicado por `model_type`; sessões de Verificação de
empresas (KYB) não são suportadas. Cada chamada acrescenta um ficheiro
(ao resultado mais recente se o passo tiver sido executado mais do que
uma vez), mantém os ficheiros existentes e regista uma entrada
`FILE_ADDED` no registo de atividade da sessão; o carregamento não envia
nenhum webhook e não altera o estado da sessão. O ficheiro é comprimido
durante o carregamento e é devolvido em `extra_files` da decisão da
sessão. Este endpoint está limitado a 10 pedidos por minuto por chave de
API. Uma chave de API com âmbito necessita de `sessions: write`, e sem
`media: read` recebe as ligações de `extra_files` como `null`.
operationId: patch_v3_session_add_images
parameters:
- name: sessionId
in: path
required: true
description: >-
UUID da sessão de Verificação de utilizadores (KYC) à qual adicionar
o ficheiro (o `session_id` retornado por `POST /v3/session/`). O ID
de uma sessão de Verificação de empresas (KYB) devolve `404`.
schema:
type: string
format: uuid
example: 11111111-2222-3333-4444-555555555555
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- model_type
properties:
file:
type: string
format: binary
description: >-
A imagem ou PDF. Extensões permitidas: `jpg`, `jpeg`, `png`,
`webp`, `tiff`, `pdf`. No máximo 15 MB aquando do
carregamento; o ficheiro é depois comprimido e rejeitado com
`400` se continuar a ter mais de 2 MB (2 097 152 bytes).
Ficheiros vazios são rejeitados.
model_type:
type: string
enum:
- kyc
- poa
description: >-
`kyc` adiciona o ficheiro ao resultado da Verificação de
identidade, `poa` ao resultado do Comprovativo de morada.
example: kyc
file_password:
type: string
description: >-
Palavra-passe de um PDF encriptado. Sem ela, ou com uma
incorreta, um PDF encriptado devolve `400`.
example:
file: (binary)
model_type: kyc
responses:
'200':
description: >-
Ficheiro adicionado. Devolve todos os ficheiros adicionais desse
resultado, incluindo o novo.
content:
application/json:
schema:
type: object
required:
- extra_files
properties:
extra_files:
type: array
description: >-
Ligações pré-assinadas de curta duração para todos os
ficheiros adicionais do resultado designado por
`model_type`, do mais antigo para o mais recente. Cada
ligação é `null` para uma chave de API com âmbito restrito
sem `media: read`. Obtenha ligações atualizadas
posteriormente a partir da decisão da sessão.
items:
type: string
format: uri
nullable: true
example:
extra_files:
- >-
https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123
'400':
description: >-
Erro de validação. Os erros de campo chegam como `{"":
[""]}`; erros de PDF encriptado como `{"detail": "..."}`.
content:
application/json:
examples:
Missing file:
summary: Nenhuma parte de ficheiro no formulário
value:
file:
- No file was submitted.
Missing model_type:
summary: model_type omitido
value:
model_type:
- This field is required.
Invalid model_type:
summary: model_type não é kyc nem poa
value:
model_type:
- '"passport" is not a valid choice.'
File too large:
summary: Carregamento superior a 15 MB
value:
file:
- File size should not exceed 15 MB
Too large after compression:
summary: Ainda superior a 2 MB após compressão
value:
file:
- File size is too big. Max allowed size is 2097152 bytes.
Encrypted PDF:
summary: PDF encriptado sem file_password
value:
detail: >-
The PDF is encrypted. Please upload a decrypted PDF or a
photo instead.
Wrong PDF password:
summary: file_password não abre o PDF
value:
detail: >-
The PDF password is incorrect. Please provide the correct
password.
'401':
description: >-
A chave de API com âmbito expirou. Este é o único caso que devolve
`401`: uma chave em falta, inválida ou revogada devolve `403`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Expired key:
summary: A data de validade da chave já passou
value:
detail: This API key has expired.
'403':
description: >-
Falha de autenticação ou autorização. Uma chave em falta devolve
`403`, assim como uma chave de outra aplicação, uma chave com âmbito
restrito sem a permissão que este endpoint requer e um pedido
proveniente de fora da lista de IPs permitidos da chave; uma chave
incorreta, revogada ou expirada devolve `401`. Distinga-as através
de `detail`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Missing or invalid credentials:
summary: Sem cabeçalho x-api-key ou a chave falhou a validação
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Other application:
summary: >-
Uma chave válida que pertence a uma aplicação diferente da
sessão
value:
detail: You do not have permission to perform this action.
Scoped key without sessions write:
summary: 'Chave com âmbito não tem sessions: write'
value:
detail: This API key has no write access to sessions.
IP not allowed:
summary: >-
Pedido proveniente de fora da lista de permissões de IP da
chave
value:
detail: This API key can't be used from this IP address.
'404':
description: >-
A sessão não existe, foi eliminada ou está fora dos limites de uma
chave com âmbito restrito; é uma sessão KYB ou não está em
`Approved`, `Declined`, `In Review` ou `Kyc Expired`; ou não tem
nenhum resultado do `model_type` solicitado (verificado antes de o
ficheiro ser validado). A pesquisa da sessão é executada antes da
verificação de credenciais, pelo que um `sessionId` desconhecido
devolve `404` mesmo sem uma chave válida.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Unknown session:
summary: Não existe nenhuma sessão com este ID ou foi eliminada
value:
detail: Not found.
Outside key limits:
summary: >-
A sessão está fora dos limites de fluxo ou dos limites que
permitem apenas sessões aprovadas de uma chave com âmbito
restrito
value:
detail: Session not found.
Not eligible:
summary: Sessão ainda não concluída, ou um ID de sessão KYB
value:
detail: No Session matches the given query.
No ID verification:
summary: model_type=kyc numa sessão sem verificação de identidade
value:
detail: The session does not have KYC data.
No Proof of Address:
summary: model_type=poa numa sessão sem comprovativo de morada
value:
detail: The session does not have POA data.
'429':
description: >-
Limite de pedidos excedido: 10 pedidos add-images por minuto por
chave de API (pedidos rejeitados também contam). O orçamento
partilhado de 300 pedidos de escrita por minuto também se aplica.
Aguarde `Retry-After` segundos antes de tentar novamente; os
cabeçalhos `X-RateLimit-*` mostram o orçamento.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Rate limited:
summary: Orçamento esgotado para o minuto atual
value:
detail: >-
Session add-images rate limit exceeded. You can make up to
10 requests per minute.
headers:
Retry-After:
description: Segundos a aguardar antes de tentar novamente.
schema:
type: integer
minimum: 1
example: 30
'503':
$ref: '#/components/responses/DocumentProcessingBusy'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/'
\
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@./back-of-id.jpg' \
-F 'model_type=kyc'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file=open("image.jpg", "rb"),
model_type="kyc",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.sessions.addImages("11111111-2222-3333-4444-555555555555", {
file: await fileFromPath("image.jpg"),
model_type: "kyc",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.SessionsAddImagesParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().addImages("11111111-2222-3333-4444-555555555555",
SessionsAddImagesParams.builder()
.file(Path.of("image.jpg"))
.modelType(SessionsAddImagesParams.ModelType.of("kyc"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->addImages('11111111-2222-3333-4444-555555555555',
[
'file' => File::fromPath('image.jpg'),
'model_type' => 'kyc',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file: Pathname("image.jpg"),
model_type: "kyc"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Sessions.AddImagesAsync("11111111-2222-3333-4444-555555555555",
new SessionsAddImagesParams
{
File = FileUpload.FromPath("image.jpg"),
ModelType = "kyc",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
responses:
DocumentProcessingBusy:
description: >-
Estão a ser processados demasiados documentos neste momento, pelo que
este carregamento não foi processado: nada foi armazenado e nenhuma
tentativa foi utilizada. Envie o mesmo ficheiro novamente após o número
de segundos em `Retry-After`. Ramifique com base no `code`, não no texto
da mensagem.
headers:
Retry-After:
description: Segundos a aguardar antes de enviar o mesmo pedido novamente.
schema:
type: integer
example: 10
content:
application/json:
schema:
type: object
required:
- detail
- code
properties:
detail:
type: string
code:
type: string
enum:
- document_processing_busy
example:
detail: We are busy processing documents. Please try again in a moment.
code: document_processing_busy
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
A chave de API da sua aplicação, a partir de Programadores -> Chaves de
API na Business Console. A chave principal tem acesso total. Uma chave
nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por
recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de
endereços IP e a uma data de validade. 401 significa que a chave está
incorreta, revogada ou expirada; 403 significa que nenhuma chave foi
enviada, que a chave não tem acesso a este recurso ou ação, ou que o
pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
sessão significa que a sessão está fora dos fluxos ou estados da chave.
Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs
como nulos, e uma chave sem permissão de escrita em sessões recebe
ligações de sessão e tokens como nulos. Consulte
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.