Visão geral

A Partner API da VULCI Banco é a interface servidor a servidor pela qual o seu sistema cria clientes, abre e consulta contas, envia PIX e TED e recebe webhooks. Toda chamada do catálogo é escopada ao parceiro dono da credencial: um parceiro só enxerga e movimenta as contas, os clientes e os webhooks que ele mesmo criou.

Base URL

A coleção e os exemplos usam a variável . Aponte para o endpoint informado pela VULCI Banco para o seu ambiente. Não use barra no final.

{{baseUrl}}/api/partner/v1

A VULCI Banco fornece a URL base de homologação e a de produção no momento da habilitação do parceiro.

Fluxo de integração

1. Receba o seu client_id e client_secret (gerados no painel da VULCI Banco).
2. Troque essas credenciais por um token de acesso em POST /api/partner/v1/oauth/token. Veja Autenticação.
3. Use o token no cabeçalho Authorization: Bearer <access_token> em todas as demais chamadas.
4. Para operações que movem dinheiro, envie um cabeçalho Idempotency-Key para evitar duplicidade.
5. Cadastre webhooks para receber eventos de forma assíncrona.

Valores monetários

• Entradas de PIX e de transferências usam centavos (número inteiro). Exemplo: 1500 representa R$ 15,00.
• Saldo, extrato e comprovante saem em reais (número com casas decimais).

Idempotência

As operações de escrita que movem dinheiro (cadastrar cliente, enviar PIX, enviar TED e transferência interna) aceitam o cabeçalho Idempotency-Key. Reenvios com a mesma chave retornam a resposta original.

Erros

As respostas de erro seguem um formato consistente, com o código HTTP apropriado:

{
  "error": {
    "status": 403,
    "message": "Permissão insuficiente para esta operação"
  }
}

Código	Significado
400	Requisição malformada
401	Token ausente, inválido ou expirado
403	Escopo insuficiente ou recurso de outro parceiro
404	Recurso não encontrado
422	Dados inválidos (validação)
429	Muitas requisições

Dois endpoints usam um formato próprio, por seguirem padrões específicos:

• O endpoint de token (POST /oauth/token) segue o padrão OAuth2 e responde { "error": "...", "error_description": "..." }.
• A validação de campos ao registrar ou atualizar webhook devolve um mapa de erros por campo: { "errors": { "url": ["mensagem"] } }.

Ferramentas

• Postman: baixe a coleção e preencha as variáveis baseUrl, client_id e client_secret. A coleção já cuida do token e do cabeçalho Authorization.
• Referência interativa: a especificação do contrato (OpenAPI) fica disponível no ambiente do Core informado pela VULCI Banco.