POST/api/v2/partners/requests

Criar Solicitação de Autorização

Cria uma nova solicitação vinculada a uma aplicação específica do parceiro autenticado.

Parâmetros

AuthorizationObrigatório
header

Token de autenticação obtido no login do parceiro.

Tipo:string

Cabeçalhos obrigatórios

CabeçalhoValorDescrição
Content-Typeapplication/jsonTipo de conteúdo enviado no corpo da requisição.
AuthorizationBearer {{ access_token }}Token de autenticação obtido no login do parceiro.

Parâmetros no corpo (JSON)

ParâmetroTipoObrigatórioDescrição
application_idstringSimID da aplicação à qual a solicitação estará vinculada.
namestringSimNome do cliente final.
documentstringSimDocumento do cliente final (CPF, CNPJ, etc).
emailstringSimE-mail do cliente final.
phonestringSimTelefone do cliente final.
originstringSimOrigem da solicitação (ex: partner).
scopesarraySimLista de escopos autorizados para a solicitação.
webhook_urlstringOpcionalURL para receber notificações sobre mudanças de status da solicitação.
metadataarrayOpcionalLista de informações adicionais relacionadas à solicitação.

Escopos Disponíveis

EscopoDescrição
cob.readLeitura de cobranças Pix
cob.writeCriação e atualização de cobranças Pix
merchants.readLeitura de estabelecimentos
merchants.writeCriação e atualização de estabelecimentos
terminals.readLeitura de terminais
terminals.writeCriação e atualização de terminais
transactions.readLeitura de transações
transactions.writeCriação e atualização de transações
webhooks.readLeitura de webhooks
webhooks.writeCriação e atualização de webhooks
dict.readLeitura de dicionários
dict.writeCriação e atualização de dicionários

Resposta de Sucesso

Em caso de sucesso, o servidor retorna um objeto JSON com os dados da solicitação criada, incluindo campos como id, status, created_at, entre outros.

Campos da Resposta

CampoTipoDescrição
idstringID único da solicitação criada.
partnerobjectDados do parceiro que fez a solicitação.
applicationobjectDados da aplicação associada à solicitação.
statusstringStatus da solicitação (pending inicialmente).
scopesarrayEscopos solicitados para a autorização.
originstringOrigem da solicitação.
namestringNome do cliente final.
documentstringDocumento do cliente final.
emailstringE-mail do cliente final.
phonestringTelefone do cliente final.
webhook_urlstringURL para receber notificações de status.
decision_atstringData da decisão do cliente (quando aplicável).
user_idstringID do usuário no sistema (quando aplicável).
account_idstringID da conta do usuário (quando aplicável).
metadataarrayInformações adicionais da solicitação.
created_atstringData de criação da solicitação (ISO8601).
updated_atstringData da última atualização da solicitação (ISO8601).

Status da Solicitação

StatusDescrição
pendingSolicitação aguardando aprovação do cliente (status inicial).
approvedSolicitação aprovada pelo cliente.
rejectedSolicitação rejeitada pelo cliente.
expiredSolicitação expirada.
cancelledSolicitação cancelada pelo parceiro.

Observações

  • O {{ access_token }} deve ser obtido via login do parceiro e inserido no cabeçalho Authorization.
  • O application_id deve ser o ID de uma aplicação previamente criada e aprovada.
  • Utilize o campo webhook_url para ser notificado sobre atualizações de status da solicitação.
  • O campo metadata permite incluir dados adicionais para referência interna.
  • Não é permitido ter múltiplas solicitações pendentes para o mesmo cliente e aplicação.
  • Os escopos solicitados devem ser um subconjunto dos escopos da aplicação.

Códigos de Resposta

CódigoSignificadoDescrição
201CreatedSolicitação criada com sucesso.
400Bad RequestParâmetros inválidos ou ausentes na requisição.
401UnauthorizedToken de autenticação inválido ou expirado.
403ForbiddenParceiro não tem permissão para criar solicitações.
409ConflictJá existe uma solicitação pendente para este cliente e aplicação.
500Internal Server ErrorErro interno do servidor.

Validações

  • Application ID: Deve ser um UUID válido de uma aplicação existente e aprovada.
  • Nome: Deve ter entre 2 e 100 caracteres.
  • Documento: Deve ser um CPF ou CNPJ válido.
  • E-mail: Deve ser um endereço de e-mail válido.
  • Telefone: Deve ter entre 10 e 15 dígitos.
  • Escopos: Deve conter pelo menos um escopo válido e deve ser subconjunto dos escopos da aplicação.
  • Webhook URL: Deve ser uma URL válida e usar HTTPS (quando fornecida).

Fluxo de Aprovação

  1. Criação: Solicitação criada com status pending.
  2. Notificação: Cliente é notificado sobre a solicitação pendente.
  3. Decisão: Cliente aprova ou rejeita a solicitação.
  4. Webhook: Parceiro recebe notificação via webhook com a decisão.
  5. Credenciais: Se aprovada, credenciais são geradas e enviadas via webhook.

Observações Importantes

  • O {{ access_token }} deve ser obtido via login do parceiro e inserido no cabeçalho Authorization.
  • O application_id deve ser o ID de uma aplicação previamente criada e aprovada.
  • Utilize o campo webhook_url para ser notificado sobre atualizações de status da solicitação.
  • O campo metadata permite incluir dados adicionais para referência interna.
curl --location 'https://dominio-ambiente.com.br/api/v2/partners/requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ access_token }}' \
--data-raw '{
  "application_id": "{{ partner_application_id }}",
  "name": "NOME DO SEU CLIENTE",
  "document": "0000000000000",
  "email": "[email protected]",
  "phone": "11999990002",
  "origin": "partner",
  "scopes": [
    "cob.read",
    "cob.write"
  ],
  "webhook_url": "https://webhook.site/601f1864-c330-4fc0-baf0-f9c5524a9bfa",
  "metadata": [
    "TESTE 1",
    "teste 2"
  ]
}'
const axios = require('axios');

const createAuthorizationRequest = async (token, requestData) => {
  try {
    const response = await axios.post('https://dominio-ambiente.com.br/api/v2/partners/requests', requestData, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });

    console.log('Solicitação criada:', response.data.id);
    console.log('Status:', response.data.status);
    
    return response.data;
    
  } catch (error) {
    console.error('Erro ao criar solicitação:', error.response?.data || error.message);
    return null;
  }
};

// Exemplo de uso
const requestData = {
  application_id: "{{ partner_application_id }}",
  name: "NOME DO SEU CLIENTE",
  document: "0000000000000",
  email: "[email protected]",
  phone: "11999990002",
  origin: "partner",
  scopes: ["cob.read", "cob.write"],
  webhook_url: "https://webhook.site/601f1864-c330-4fc0-baf0-f9c5524a9bfa",
  metadata: ["TESTE 1", "teste 2"]
};

const token = "{{ access_token }}";
createAuthorizationRequest(token, requestData);
import requests
import json

def create_authorization_request(token, request_data):
    url = "https://dominio-ambiente.com.br/api/v2/partners/requests"
    
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    
    try:
        response = requests.post(url, json=request_data, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        
        print(f"Solicitação criada: {data['id']}")
        print(f"Status: {data['status']}")
        print(f"Cliente: {data['name']}")
        print(f"Documento: {data['document']}")
        
        return data
        
    except requests.exceptions.RequestException as e:
        print(f"Erro na requisição: {e}")
        return None

# Exemplo de uso
request_data = {
    "application_id": "{{ partner_application_id }}",
    "name": "NOME DO SEU CLIENTE",
    "document": "0000000000000",
    "email": "[email protected]",
    "phone": "11999990002",
    "origin": "partner",
    "scopes": ["cob.read", "cob.write"],
    "webhook_url": "https://webhook.site/601f1864-c330-4fc0-baf0-f9c5524a9bfa",
    "metadata": ["TESTE 1", "teste 2"]
}

token = "{{ access_token }}"
result = create_authorization_request(token, request_data)
<?php

function createAuthorizationRequest($token, $requestData) {
    $url = 'https://dominio-ambiente.com.br/api/v2/partners/requests';
    
    // Configuração do cURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $token
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    curl_close($ch);
    
    if ($error) {
        echo "Erro cURL: " . $error . "\n";
        return null;
    }
    
    if ($httpCode !== 200 && $httpCode !== 201) {
        echo "Erro HTTP: " . $httpCode . "\n";
        echo "Resposta: " . $response . "\n";
        return null;
    }
    
    $data = json_decode($response, true);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        echo "Erro ao decodificar JSON: " . json_last_error_msg() . "\n";
        return null;
    }
    
    echo "Solicitação criada: " . $data['id'] . "\n";
    echo "Status: " . $data['status'] . "\n";
    
    return $data;
}

// Exemplo de uso
$requestData = [
    'application_id' => '{{ partner_application_id }}',
    'name' => 'NOME DO SEU CLIENTE',
    'document' => '0000000000000',
    'email' => '[email protected]',
    'phone' => '11999990002',
    'origin' => 'partner',
    'scopes' => ['cob.read', 'cob.write'],
    'webhook_url' => 'https://webhook.site/601f1864-c330-4fc0-baf0-f9c5524a9bfa',
    'metadata' => ['TESTE 1', 'teste 2']
];

$token = '{{ access_token }}';
createAuthorizationRequest($token, $requestData);
?>
{
  "id": "req-123-456-789",
  "partner": {
    "id": "partner-abc-def",
    "name": "Minha Empresa",
    "contact_email": "[email protected]",
    "contact_phone": "11999999999",
    "status": "active",
    "scopes": ["cob.read", "cob.write", "merchants.read"]
  },
  "application": {
    "id": "app-123-456-789",
    "name": "Sistema de Cobrança",
    "description": "Aplicação para gerenciar cobranças Pix",
    "briefing": "Facilita a criação e gestão de cobranças",
    "category": "Pagamentos",
    "scopes": ["cob.read", "cob.write"],
    "status": "active"
  },
  "status": "pending",
  "scopes": [
    "cob.read",
    "cob.write"
  ],
  "origin": "partner",
  "name": "NOME DO SEU CLIENTE",
  "document": "0000000000000",
  "email": "[email protected]",
  "phone": "11999990002",
  "webhook_url": "https://webhook.site/601f1864-c330-4fc0-baf0-f9c5524a9bfa",
  "decision_at": null,
  "user_id": null,
  "account_id": null,
  "metadata": [
    "TESTE 1",
    "teste 2"
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}