Pular para o conteúdo principal
Upload Document
curl --request POST \
  --url https://api.spherepay.co/v2/document \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form targetId=customer_66c4168d418a410eae282b83883bdc39 \
  --form target=customer \
  --form documentType=passport \
  --form country=USA \
  --form side=front \
  --form 'description=Passport photo page' \
  --form 'file=(binary)' \
  --form 0.file='@example-file' \
  --form 1.file='@example-file' \
  --form 2.file='@example-file' \
  --form 3.file='@example-file' \
  --form 4.file='@example-file' \
  --form 5.file='@example-file'
import requests

url = "https://api.spherepay.co/v2/document"

files = {
    "0.file": ("example-file", open("example-file", "rb")),
    "1.file": ("example-file", open("example-file", "rb")),
    "2.file": ("example-file", open("example-file", "rb")),
    "3.file": ("example-file", open("example-file", "rb")),
    "4.file": ("example-file", open("example-file", "rb")),
    "5.file": ("example-file", open("example-file", "rb"))
}
payload = {
    "targetId": "customer_66c4168d418a410eae282b83883bdc39",
    "target": "customer",
    "documentType": "passport",
    "country": "USA",
    "side": "front",
    "description": "Passport photo page",
    "file": "(binary)"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)
const form = new FormData();
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');
form.append('target', 'customer');
form.append('documentType', 'passport');
form.append('country', 'USA');
form.append('side', 'front');
form.append('description', 'Passport photo page');
form.append('file', '(binary)');
form.append('0.file', '{
  "fileName": "example-file"
}');
form.append('1.file', '{
  "fileName": "example-file"
}');
form.append('2.file', '{
  "fileName": "example-file"
}');
form.append('3.file', '{
  "fileName": "example-file"
}');
form.append('4.file', '{
  "fileName": "example-file"
}');
form.append('5.file', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.spherepay.co/v2/document', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/document",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/document"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/document")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/document")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body
{
  "id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "targetId": "customer_66c4168d418a410eae282b83883bdc39",
  "target": "customer",
  "documentType": "passport",
  "country": "USA",
  "side": "front",
  "description": "Passport photo page",
  "fileName": "passport_front_20250101.pdf",
  "fileSize": 2048576,
  "mimeType": "application/pdf",
  "createdAt": "2025-12-31T10:30:00.000Z"
}
{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}
{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}
{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}
Envie um documento de identidade para um cliente ou representante empresarial como parte do processo de verificação KYC ou KYB. Os documentos são submetidos como dados de formulário multipart. Os formatos de arquivo aceitos são PDF, JPEG, PNG, HEIC e TIFF, com tamanho máximo de arquivo de 15 MB. Os campos target e documentType determinam como o SpherePay roteará e processará o envio — clientes individuais, clientes empresariais e representantes empresariais possuem seus próprios conjuntos de tipos de documentos aceitos.
Documentos para clientes individuais são enviados com target: "customer". Documentos para representantes empresariais (UBOs) usam target: "business_representative" e o targetId deve ser o ID do representante, não o do cliente.

Autorizações

​
Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

multipart/form-data

Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back).

​
targetId
string
obrigatório

The unique identifier of the target entity for which the document is being uploaded

Minimum string length: 1
Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

​
file
file
obrigatório

The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 10MB

​
country
string
obrigatório

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.

Exemplo:

"USA"

​
target
enum<string>
obrigatório

The target entity for which the document is being uploaded

Opções disponíveis:
customer
Exemplo:

"customer"

​
documentType
enum<string>
obrigatório

ID documents for individual customers. See Document Guideline for requirements.

Opções disponíveis:
passport,
drivers,
id_card,
residence_permit
Exemplo:

"passport"

​
description
string

Optional description or notes about the document

Exemplo:

"Front side of driver's license"

​
side
enum<string>

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Opções disponíveis:
front,
back
Exemplo:

"front"

Resposta

Response for an ID document uploaded for an individual customer.

​
id
string
obrigatório

The unique identifier of the document

Exemplo:

"documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

​
targetId
string
obrigatório

The unique identifier of the target entity for which the document is being uploaded

Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

​
createdAt
string
obrigatório

The date and time the document was created

Exemplo:

"2025-12-31T10:30:00.000Z"

​
fileName
string
obrigatório

The name of the document file

Exemplo:

"passport_front_20250101.pdf"

​
fileSize
number
obrigatório

The size of the document in bytes

Exemplo:

2048576

​
mimeType
string
obrigatório

The MIME type of the document file

Exemplo:

"application/pdf"

​
description
string
obrigatório

The description of the document

Exemplo:

"Passport photo page"

​
target
enum<string>
obrigatório

The target entity for which the document is being uploaded

Opções disponíveis:
customer
Exemplo:

"customer"

​
documentType
enum<string>
obrigatório

The type of the document

Opções disponíveis:
drivers,
passport,
id_card,
residence_permit
Exemplo:

"passport"

​
country
string
obrigatório

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA)

Exemplo:

"USA"

​
side
enum<string>
obrigatório

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Opções disponíveis:
front,
back
Exemplo:

"front"

Última modificação em 22 de junho de 2026